1. Program documentation using the Javadoc tool 1 Program documentation Using the Javadoc tool

2. Program documentation using the Javadoc tool 2 JavaDoc J2SE comes with a tool to extract comments from Java source code to produce program documentation in HTML format. Doc comments –/** ….*/ –Written immediately before the programming part to document. Ordinary comments –/* …*/ –// –Not used in program documentation.

3. Program documentation using the Javadoc tool 3 Doc comments Plain text –Be careful with HTML tags 1 < B must be written A < Blt ~ less than Salary > 0 must be written salary > 0gt ~ greater than HTML –The HTML you write in the JavaDoc comments, will be inserted into the generated HTML files. –Don’t use tags like,, etc. These tags are generated by the Javadoc tool. Special tags (not HTML, but doc tags) –@author –@since version number –@deprecated The compiler issues a warning if you use classes or methods tagged @deprecated. –{@code text} Wrapped in … HTML tags For program examples, etc.

4. Program documentation using the Javadoc tool 4 What to document? All public and protected parts of a program should be documented using JavaDoc comments –Package-protected and private parts are not that important to document since they are only for internal use. Classes –Write JavaDoc comments in front of the class declaration. Methods –Parameters to the method @param –Return values @return –Exceptions thrown from the method @throws Checked exceptions Runtime exceptions that the caller might reasonably want to catch.

5. Program documentation using the Javadoc tool 5 Documenting methods Document the contract between the method and it callers –Focus on what the method does, not how –Preconditions –Postconditions –Side effects –Thread safety

6. Program documentation using the Javadoc tool 6 Generating HTML files Command line –Javadoc file.java Generate HTML files for a single Java file –Javadoc *.java Generate HTML files for all Java files (in the current directory) –Javadoc –author file.java Include @author information in HTML files –Javadoc –private file.java Generate HTML files for private parts of the program. –Lots of other options.

7. Program documentation using the Javadoc tool 7 Style Look at the HTML files of the existing class library in J2SE. Use the JavaDoc tag {@code parameter} for code examples, keywords, class names, methods names, etc. Use 3 rd person, not 2 nd person –Gets the label(right) –Get the label(wrong)

8. Program documentation using the Javadoc tool 8 NetBeans assistance NetBeans can help you write JavaDoc comments in your Java files NetBeans can activate the JavaDoc program to generate the HTML pages.

9. Program documentation using the Javadoc tool 9 Technical writers vs. programmers Programmers are supposed to write the program code and the doc comments. Programmers are usually better at writing code than comments. Some companies employ technical writers who write program documentation –Doc comments Both programmer and technical writer need write access to the program files. –Reference documentation –User manuals –Tutorials

10. Program documentation using the Javadoc tool 10 References Sun Microsystems Java Doc Tool Homepage –http://java.sun.com/j2se/javadoc/index.j sphttp://java.sun.com/j2se/javadoc/index.j sp Sun Microsystems How to Write Doc Comments for the Javadoc Tool –http://java.sun.com/j2se/javadoc/writing doccomments/index.htmlhttp://java.sun.com/j2se/javadoc/writing doccomments/index.html –Sun’s internal standards for writing doc comments. Arnold et al. The Java Programming Language 4th edition, Addison Wesley 2006 –Chapter 19 Documentation Comments, page 481-498 –Introduction with emphasis on JavaDoc tags. Joshua Bloch Effective Java, Addison Wesley 2001 –Item 28: Write doc comments for all exposed API elements, page 136-139