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

Program documentation using the Javadoc tool

1

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

Doc comments• Plain text

– Be careful with HTML tags• 1 < B must be written A < B lt ~ less than• Salary > 0 must be written salary > 0 gt ~ greater than

• HTML– The HTML you write in the JavaDoc comments, will be inserted into the

generated HTML files.– Don’t use tags like <html>, <head>, <body> 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 <code>…</code> HTML tags• For program examples, etc.


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

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

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

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 3rd person, not 2nd person– Gets the label (right)– Get the label (wrong)


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

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

References• Sun Microsystems Java Doc Tool

Homepage – http://java.sun.com/j2se/javadoc/index.

jsp

• Sun Microsystems How to Write Doc Comments for the Javadoc Tool– http://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

http://java.sun.com/j2se/javadoc/index.jsp

http://java.sun.com/j2se/javadoc/index.jsp

http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

Documents

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