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 * 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 - Tag Use style for keywords and names. Keywords and names are offset by... when mentioned in a description. This includes: Java keywords Code examples...

JavaDoc - Tag package names class names method names interface names field names argument names

JavaDoc - Tag Example: An applet is marked active just before its start method is called. Returns an Image object that can then be painted on the screen The name argument is case insensitive.

JavaDoc - Tag NullPointerException if the entry name is man the optional true if the applet is active; false otherwise.

JavaDoc Tag param_name description Applicable to methods and constructors. tags should be listed in argument-declaration order.

JavaDoc Tag description Applicable to 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 Tag true if the String are equal; false a hash code value for this object.

JavaDoc Tag 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. Replaced by setBounds(int, int, int, As of JDK 1.1, replaced by #setBounds(int,int,int,int)} If the API is obsolete and there is no replacement, the argument should be "No replacement".

JavaDoc Tag 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 java.lang.String // java.lang.String The String class // The String Java Spec // Java Spec A doc comment may contain tags.

JavaDoc 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 classname is significant. If there is more than one argument, there must be a single blank character between the arguments. java.io.File#File(java.io.File, java.lang.String)

JavaDoc Tag Syntax 1: APIName Label} Syntax 2: reference} Adds an inline link to other tag begins and ends with curly braces to separate it from the rest of the inline text.

JavaDoc Tag A doc comment may contain multiple tags. Example: … contains a link Class#getClassLoader() loader} to … … by Class#getClassLoader()} is...

JavaDoc Tag 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 Tag Both and are is introduced in JDK1.0 is introduced in JDK1.2 Tag.

Javadocs - HTML Tag Simple tags << >> Space \\ && "“ New line

Javadocs - HTML Tag - paragraph If you have more than one paragraph in the doc comment, separate the paragraphs with a paragraph tag. … - Bold … - Italic … - Underline

Javadocs - HTML Tag SuperScript - tag Example: 2 32 Subscript - tag Example: log 2

Javadocs - HTML Tag … - Fixed Width Font Used in class name, method name, interface name, field name. Similar to “ … ”. … - Indent

Javadocs - HTML Tag - used to write the code snipets. Also use for intend. Example: * * void printClassName(Object obj) * { * String name= obj.getClass().getName()); *.... * } *

Javadocs - HTML Tags Bullet Item Bullet 1 Bullet 2 Bullet 3

Javadocs - HTML Tags Number Item Item 1 Item 2 Item 3

Javadocs - HTML Tag Table 1x1 1x2 2x1 2x2

JavaDocs - Questions What is the difference ? What is the difference ?

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 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 Write Doc Comments for the Javadoc tool