JavaDoc guidelines
Download
Report
Transcript JavaDoc guidelines
Java Doc Guideline
R.SANTHANA GOPALAN
Java Doc Guideline
Audience
Internal Developers
PQA - who write test plans
PPT – who write the documentation
Customers – 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 parts
1. 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 begincomment symbol (/**) followed by a
return.
Subsequent lines start with an asterisk *.
This line is indented to line up with the code
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.  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 description
Applicable 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
@see java.lang.String The String class
// String
// 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
<
>
\
&
"
<br>
<
>
Space
\
&
“
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 - <sup> </sup> tag
Example:
2<sup>32</sup>
232
Subscript - <sub> </sub> tag
Example:
log<sub>2</sub>
log2
Javadocs - HTML Tag
<tt>…</tt> - Fixed Width Font
Used
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 Links
Writing Java API Specification
http://cm-server/training/gen_writingapispecs.html
Write Doc Comments for the Javadoc tool
http://cm-server/training/general_writingdoccomments.html