javadoc

1
javadoc
2
What is javadoc?
javadoc is a tool that parses the declarations
and documentations in a set of Java source files
and generates API documentation in HTML format
(by default).  Javadoc is distributed with each
SDK.
3
How does it work?
This utility pulls out the important information
concerning the classes, inner classes,
interfaces, constructors, methods, and fields,
and automatically generates documentation in HTML
format.
4
Access to javadoc (1)

• Eclipse provides access directly to javadoc
  functionality.
• FilegtExportgtjavadocgtjavadoc command
• This should point to the javadoc utility on
  your computer which is usually the
  c\j2sdk_1.42\bin\javadoc.exe, but variations may
  exist.

5
Access to javadoc (2)

• Javadoc may also be invoked from the command line
  form either windows or unix. In either case you
  may need to specify the path to javadoc.
• In Windows, run cmd to bring up a dos shell then
  type javadoc.
• In Unix, type javadoc in the shell.

6
doc-comments

• The documentation, text, intended to be processed
  by javadoc are placed in special comments
  referred to as doc-comments.
• A doc-comment consists of the characters between
  the / that begins the comment and the / that
  ends it. 

7
Conventions

• Text intended for javadoc must be placed in
  doc-comments that begin with / and end with
  /.
• Doc-comments for a class or method must be placed
  immediately before the class or method
  declaration.
• The first sentence for a doc-comment should be a
  one-sentence summary of the class or method being
  documented.

8
Tags in javadoc

• javadoc parses special tags that are recognized
  when they are embedded within a doc-comment. 
• These doc tags enable you to autogenerate a
  complete, well-formatted API from your source
  code. The tags start with an "at" sign (_at_) and
  are case-sensitive.

9
Current Tags
_at_author 1.0 _at_deprecated 1.0 _at_exception 1.0 _at_
link 1.2 _at_param 1.0 _at_return 1.0 _at_see 1.0
_at_serial 1.2 _at_serialData 1.2 _at_serialField 1.2
_at_since 1.1 _at_throws 1.2 _at_version 1.0
10
Tags of Most Import

• _at_author
• Creates an "Author" entry.  A doc comment may
  contain multiple _at_author tags.
• _at_throws Exception-class-name  description
• Adds a "Throws" subheading to the generated
  documentation, with the class-name and
  description text for each Exception.

11
Tags of Most Import (2)

• _at_param  parameter-name description
• Adds a parameter to the "Parameters" section. The
  description may be continued on the next line.
• _at_return  description
• Adds a "Returns" section, which contains the
  description of the return value.

12
Tags of Most Import (3)

• _at_version  version-text
• Adds a "Version" subheading with the specified
  version-text to the generated docs when the
  -version option is used. The text has no special
  internal structure. A doc comment may contain at
  most one _at_version tag.

13
Style (1)

• Proper form is to include _at_param for each
  parameter in the signature of a method.
• Proper form is to include _at_throws for each
  exception that is explicitly thrown in the method.

14
Style (2)

• Changing source code fonts in javadoc tags helps
  items stand out from the rest of the description.
• Placing import statements between the class
  comment and the class declaration is a logic
  error.

15
javadoc and Eclipse (1)

• WindowgtPreferences gt Java gt Code Style gt Code
  Template gt CodegtNew Java Files
• package_declaration
• /
• Created on dateltbrgt
• Author Richard Upchurchltbrgt
• Description
• /
• type_declaration

16
javadoc and Eclipse (2)

• WindowgtPreferences gt Java gt Code Style gt Code
  Template gt CommentsgtMethods
• /
• ltdescription of methodgt
• _at_requires.
• _at_modifies.
• _at_effects.
• tags
• /

17
Note

• The _at_requires., _at_modifies. and _at_effects. tags are
  not standard javadoc tags therefore they must be
  processed differently.
• Be sure there is a space after the . in each of
  these tags.

18
Javadoc and Eclipse (3)

• Type method signature
• Select method name
• SourcegtAdd Javadoc Comment
• Place the comment template preceding your
  methods signature.
• You complete the information needed.

19
Customized Tags

• We have introduced custom tags in our
  documentation. To force javadoc to recognize
  the tags, we are allowed to include options on
  the command line.
• javadoc -breakiterator _at_javadoc-tag.txt
  lab5/SearchUtilities.java -d lab5/doc

20
Explanation

• javadoc -breakiterator _at_javadoc-tag.txt
  lab5/SearchUtilities.java -d lab5/doc
• javadoc -breakiterator _at_filepath-for-custom-tag-fi
  le sourcepath -d documentation-path
• Its wise to specify a directory to place ALL
  the files.

21
Output

• All the documentation files are placed in the
  destination-path directory. These are all html
  files.

22
Custom Tag File

• -tag requires.mRequires
• -tag modifies.mModifies
• -tag effects.mEffects
• -tag says I have custom tags
• requires., modifies., and effects. Tell the name
  of those custom tags.
• m says applies to methods
• Requires, Modifies, and Effects are the
  substitutions for the documentation.

23
Arguments

• There are additional arguments to javadoc that
  you can apply. Default is to produce
  doc-comments for public members and methods.
• Use -private to generate doc-comments for all
  members and methods.

24
References
http//java.sun.com/j2se/javadoc/writingdoccomment
s/index.html
http//java.sun.com/j2se/javadoc/index.jsp
http//bazaar.sis.pitt.edu/jdtutorial/index.html