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 * * @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 "<" immediately after the period. Example: /** * This is a simulation of Dr.&nbsp Watson Unix computer. */

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

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

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

15. JavaDoc - Tag Example: @throws NullPointerException if the entry name is null @param man the optional Manifest @return true if the applet is active; false otherwise.

16. JavaDoc - @param Tag Syntax: @param param_name description Applicable to methods and constructors. Multiple @param tags should be listed in argument-declaration order.

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

18. JavaDoc - @return Tag Example: @return true if the String are equal; false otherwise. @return a hash code value for this object.

19. 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".

20. 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 Java Spec // Java Spec A doc comment may contain multiple @see tags.

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

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

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

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

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

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

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

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

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

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

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

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

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

34. JavaDocs - Questions What is the difference between @throws and @exception ? What is the difference between @see and @link ?

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

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

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

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_writingdoccomments.html