Java Doc Guideline

1
Java Doc Guideline

• R.SANTHANA GOPALAN

2
Java Doc Guideline

• Audience
• Internal Developers
• PQA - who write test plans
• PPT who write the documentation
• Customers who are writing/customizing the
  application.

3
Java Doc source

• The Javadoc tool can generate output originating
  from four different types of "source" files
• Java Source code
• Package comment files - these contain package
  comments
• Overview comment files - these contain comments
  about the set of packages
• Miscellaneous unprocessed files - these include
  images, sample source code, class files, applets,
  HTML files, and whatever else you might want to
  reference from the previous files.

4
JavaDoc Comment

• JavaDoc Comment Consists of two parts
• 1. Description
• 2. Tags
• A doc comment may have zero or more tags.
• JavaDoc comment starts with / and ends with
  /.

5
JavaDoc - sample

• Sample
• /
• This is the description part of a doc comment
• _at_tag Comment for the tag
• /

6
JavaDoc - Coding Standard

• The first line starts with the begin-comment
  symbol (/) followed by a return.
• This line is indented to line up with the code
• Subsequent lines start with an asterisk .
• They are indented an additional space so the
  asterisks line up.
• A space separates the asterisk from the
  descriptive text or tag that follows it.

7
JavaDoc - Coding Standard

• Insert a blank comment line between the
  description and the list of tags, as shown.
• Insert additional blank lines to create "blocks"
  of related tags (discussed in greater detail
  below).

8
JavaDoc Description text

• Description may have multiple sentences but first
  sentence is very important.
• The first sentence of each doc comment should be
  a summary sentence.
• The first sentence should be concise but complete
  description of the API item
• Write summary sentences that distinguish
  overloaded methods from each other.

9
JavaDoc Description

• Example
• /
• Class constructor specifying number of
  objects to create.
• /
• foo(int n)

10
JavaDoc Description

• How Javadoc tool identified the first sentence?
• JavaDoc first sentence ends at the first period
  that is followed by a blank, tab, or line
  terminator, or at the first tag.
• Question
• How to solve if the first sentence required . .
  In otherwords how do include Dr. Watson in
  first sentence

11
JavaDoc Description

• Answer
• Typing an HTML meta-character such as "" or "lt"
  immediately after the period.
• Example
• /
• This is a simulation of Dr.nbsp Watson Unix
  computer.
• /

12
JavaDoc - ltcodegt Tag

• Use ltcodegt style for keywords and names.
• Keywords and names are offset by
  ltcodegt...lt/codegt when mentioned in a description.
  This includes
• Java keywords
• Code examples
• ...

13
JavaDoc - ltcodegt Tag

• package names
• class names
• method names
• interface names
• field names
• argument names

14
JavaDoc - ltcodegt Tag

• Example
• An applet is marked active just before its
  ltcodegtstartlt/codegt method is called.
• Returns an ltcodegtImagelt/codegt object that can
  then be painted on the screen
• The ltcodegtnamelt/codegt argument is case
  insensitive.

15
JavaDoc - ltcodegt Tag

• Example
• _at_throws NullPointerException if the entry name is
  ltcodegtnulllt/codegt
• _at_param man the optional ltcodegtManifestlt/codegt
• _at_return ltcodegttruelt/codegt if the applet is
  active ltcodegtfalselt/codegt otherwise.

16
JavaDoc - _at_param Tag

• Syntax _at_param param_name description
• Applicable to methods and constructors.
• Multiple _at_param tags should be listed in
  argument-declaration order.

17
JavaDoc - _at_return Tag

• Syntax _at_return description
• Applicable to methods
• _at_return tag is required for every method that
  returns something other than void.
• Whenever possible, supply return values for
  special cases (such as specifying the value
  returned when an out-of-bounds argument is
  supplied).

18
JavaDoc - _at_return Tag

• Example
• _at_return ltcodegttruelt/codegt if the ltcodegtString
  lt/codegtare equal ltcodegtfalselt/codegt otherwise.
• _at_return a hash code value for this object.

19
JavaDoc - _at_deprecated Tag

• Syntax _at_deprecated description
• Indicates that this API should no longer be used
  (even though it may continue to work). By
  convention, the text describes the API (or APIs)
  which replace the deprecated API.
• Example
• _at_deprecated Replaced by setBounds(int, int, int,
  int)
• _at_deprecated As of JDK 1.1, replaced by _at_link
  setBounds(int,int,int,int)
• If the API is obsolete and there is no
  replacement, the argument to _at_deprecated should
  be "No replacement".

20
JavaDoc - _at_see Tag

• Syntax _at_see APIName Label
• Adds a hyperlinked "See Also" entry to the class
  documentation. APIName can be the name of a Java
  API or an HTML anchor
• Example
• _at_see java.lang.String
  // String
• _at_see java.lang.String The String class
  // The String class
• _at_see ltA HREF"spec.html"gtJava Speclt/agt // Java
  Spec
• A doc comment may contain multiple _at_see tags.

21
JavaDoc - _at_see Tag

• The character separates the name of a class
  from the name of one of its fields, methods, or
  constructors. One of several overloaded methods
  or constructors may be selected by including a
  parenthesized list of argument types after the
  method or constructor name. Whitespace in _at_see's
  classname is significant. If there is more than
  one argument, there must be a single blank
  character between the arguments.
• Example
• _at_see java.io.FileFile(java.io.File,
  java.lang.String)

22
JavaDoc - _at_link Tag

• Syntax 1 _at_link APIName Label
• Syntax 2 _at_link reference
• Adds an inline link to other documentation.
• _at_link tag begins and ends with curly braces to
  separate it from the rest of the inline text.

23
JavaDoc - _at_link Tag

• A doc comment may contain multiple _at_link tags.
• Example
• contains a _at_ link ClassgetClassLoader()
  loader to
• by _at_link ClassgetClassLoader() is ...

24
JavaDoc - _at_throws Tag

• Syntax _at_throws class-name description
• Adds a "Throws" subheading to the generated
  documentation, with the class-name and
  description text.
• The class-name is the name of the exception that
  may be thrown by the method.

25
JavaDoc - _at_exception Tag

• Both _at_throws and _at_exception are same.
• _at_exception is introduced in JDK1.0 and _at_throws is
  introduced in JDK1.2
• Use _at_throws Tag.

26
Javadocs - HTML Tag

• Simple tags

lt lt
gt gt
nbsp Space
92 \
amp
quot
ltbrgt New line
27
Javadocs - HTML Tag

• ltpgt - paragraph
• If you have more than one paragraph in the doc
  comment, separate the paragraphs with a ltpgt
  paragraph tag.
• ltbgtlt/bgt - Bold
• ltigt lt/igt - Italic
• ltugtlt/ugt - Underline

28
Javadocs - HTML Tag

• SuperScript - ltsupgt lt/supgt tag
• Example
• 2ltsupgt32lt/supgt
• 232
• Subscript - ltsubgt lt/subgt tag
• Example
• logltsubgt2lt/subgt
• log2

29
Javadocs - HTML Tag

• ltttgtlt/ttgt - Fixed Width Font
• Used in class name, method name, interface name,
  field name.
• Similar to ltcodegtlt/codegt.
• ltblockquotegt lt/blockquotegt - Indent

30
Javadocs - HTML Tag

• ltpregt lt/pregt - used to write the code snipets.
  Also use ltbockquotegt lt/blockquotegt for intend.
• Example
• ltblockquotegtltpregt
• void printClassName(Object obj)
• String name obj.getClass().getName())
• .. ..
• lt/pregtlt/blockquotegt

31
Javadocs - HTML Tags

• Bullet Item
• ltulgt
• ltligt Bullet 1 lt/ligt
• ltligt Bullet 2 lt/ligt
• ltligt Bullet 3 lt/ligt
• lt/ulgt

32
Javadocs - HTML Tags

• Number Item
• ltolgt
• ltligt Item 1 lt/ligt
• ltligt Item 2 lt/ligt
• ltligt Item 3 lt/ligt
• ltolgt

33
Javadocs - HTML Tag

• Table
• lttablegt
• lttrgt
• lttdgt 1x1 lt/tdgt lttdgt 1x2 lt/tdgt
• lt/trgt
• lttrgt
• lttdgt 2x1 lt/tdgt lttdgt2x2 lt/tdgt
• lt/trgt
• lt/tablegt

34
JavaDocs - Questions

• What is the difference between _at_throws and
  _at_exception ?
• What is the difference between _at_see and _at_link ?

35
JavaDocs - QA

• How to include Overrides in JavaDoc?
• Javadoc tool identified the Override methods and
  include into JavaDoc. We dont need to worry
  about this.
• Example java.lang.String.equals() overrides
  equals() in class java.lang.Object.

36
JavaDocs - QA

• Is there any way to exclude the particular
  public method?
• Now there is no solution.
• Sun has proposed to introduce _at_exclude tag to
  solve this problem.
• Another way is simply ignore particular class.

37
JavaDocs - QA

• Is there any easy way to find the missing
  JavaDocs?
• Using the Doclet we can easily find.
• We are using doclint doclet to find the missing
  JavaDocs.

38
JavaDocs - Reference

• Reference Links
• Writing Java API Specification
• http//cm-server/training/gen_writingapispecs.html
  
• Write Doc Comments for the Javadoc tool
• http//cm-server/training/general_writingdoccommen
  ts.html