Java Doc Guideline

R.SANTHANA GOPALAN

Java Doc Guideline

Audience Internal Developers PQA - who write test plansPPT – who write the documentationCustomers – who are writing/customizing

the application.

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.

JavaDoc Comment

JavaDoc Comment Consists of two parts1. Description

2. Tags

A doc comment may have zero or more tags.

JavaDoc comment starts with “/**” and ends with “*/”.

JavaDoc - sample

Sample:/**

* This is the description part of a doc comment

*

* @tag Comment for the tag

*/

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.

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).

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.

JavaDoc – Description

Example

/**

* Class constructor specifying number of objects to create.

*/

foo(int n)

{

…

}

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

JavaDoc – Description

Answer:Typing an HTML meta-character such as

"&" or "<" immediately after the period.Example:/**

* This is a simulation of Dr.&nbsp Watson Unix computer.

*/

JavaDoc - <code> Tag

Use <code> style for keywords and names.

Keywords and names are offset by <code>...</code> when mentioned in a description. This includes:

Java keywords Code examples ...

JavaDoc - <code> Tag

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

JavaDoc - <code> Tag

Example:An applet is marked active just before its <code>start</code> method is called.

Returns an <code>Image</code> object that can then be painted on the screen

The <code>name</code> argument is case insensitive.

JavaDoc - <code> Tag

Example:@throws NullPointerException if the entry name is <code>null</code>

@param man the optional <code>Manifest</code>

@return <code>true</code> if the applet is active; <code>false</code> otherwise.

JavaDoc - @param Tag

Syntax: @param param_name description

Applicable to methods and constructors.Multiple @param tags should be listed in

argument-declaration order.

JavaDoc - @return Tag

Syntax: @return descriptionApplicable to methods @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).

JavaDoc - @return Tag

Example:@return <code>true</code> if the <code>String </code>are equal; <code>false</code> otherwise.

@return a hash code value for this object.

JavaDoc - @deprecated Tag

Syntax: @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: @deprecated Replaced by setBounds(int, int,

int, int)@deprecated As of JDK 1.1, replaced by {@link

#setBounds(int,int,int,int)} If the API is obsolete and there is no replacement,

the argument to @deprecated should be "No replacement".

JavaDoc - @see Tag

Syntax: @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:@see java.lang.String // String @see java.lang.String The String class // The String class

@see <A HREF="spec.html">Java Spec</a> // Java Spec A doc comment may contain multiple @see

tags.

JavaDoc - @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 @see's classname is significant. If there is more than one argument, there must be a single blank character between the arguments.

Example: @see java.io.File#File(java.io.File, java.lang.String)

JavaDoc - @link Tag

Syntax 1: {@link APIName Label}Syntax 2: {@link reference}

Adds an inline link to other documentation.

@link tag begins and ends with curly braces to separate it from the rest of the inline text.

JavaDoc - @link Tag

A doc comment may contain multiple {@link} tags.

Example:… contains a {@ link

Class#getClassLoader() loader} to …… by {@link Class#getClassLoader()} is ...

JavaDoc - @throws Tag

Syntax: @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.

JavaDoc - @exception Tag

Both “@throws” and “@exception” are same.

@exception is introduced in JDK1.0 and @throws is introduced in JDK1.2

Use @throws Tag.

Javadocs - HTML Tag

Simple tags

&lt; <

&gt; >

&nbsp; Space

&#92; \

&amp; &

&quot; “

<br> New line

Javadocs - HTML Tag

<p> - paragraph If you have more than one paragraph in the

doc comment, separate the paragraphs with a <p> paragraph tag.

<b>…</b> - Bold<i>… </i> - Italic<u>…</u> - Underline

Javadocs - HTML Tag

SuperScript -  tagExample:

2³² 232

Subscript -  tagExample:

log₂ log2

Javadocs - HTML Tag

<tt>…</tt> - Fixed Width FontUsed in class name, method name,

interface name, field name.Similar to “<code>…</code>”.

<blockquote>… </blockquote> - Indent

Javadocs - HTML Tag

<pre> </pre> - used to write the code snipets. Also use <bockquote> </blockquote> for intend.

Example:* <blockquote><pre>* void printClassName(Object obj) * {* String name= obj.getClass().getName());* .. .. * }* </pre></blockquote>

Javadocs - HTML Tags

Bullet Item<ul>

<li> Bullet 1 </li>

<li> Bullet 2 </li>

<li> Bullet 3 </li>

</ul>

Javadocs - HTML Tags

Number Item<ol>

<li> Item 1 </li>

<li> Item 2 </li>

<li> Item 3 </li>

<ol>

Javadocs - HTML Tag

Table<table>

<tr>

<td> 1x1 </td> <td> 1x2 </td>

</tr>

<tr>

<td> 2x1 </td> <td>2x2 </td>

</tr>

</table>

JavaDocs - Questions

What is the difference between @throws and @exception ?

What is the difference between @see and @link ?

JavaDocs - Q&A

How to include “Overrides:” in JavaDoc?Javadoc tool identified the Override

methods and include into JavaDoc. We don’t need to worry about this.

Example: java.lang.String.equals() overrides equals() in class java.lang.Object.

JavaDocs - Q&A

Is there any way to exclude the particular “public” method?Now there is no solution.Sun has proposed to introduce “@exclude”

tag to solve this problem.Another way is simply ignore particular

class.

JavaDocs - Q&A

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.

JavaDocs - Reference

Reference LinksWriting Java API Specification

http://cm-server/training/gen_writingapispecs.html

Write Doc Comments for the Javadoc tool http://cm-server/training/

general_writingdoccomments.html