Program documentation

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
• A lt B must be written A lt B
• HTML
• The HTML you write in the JavaDoc comments will
  be inserted into the generated HTML files.
• Dont use tags like lthtmlgt, ltheadgt, ltbodygt etc.
• These tags are generated by the Javadoc tool.
• Special tags (not HTML, but doc tags)
• _at_author
• _at_since version number
• _at_deprecated
• The compiler issues a warning if you use classes
  or methods tagged _at_deprecated.
• _at_code text
• Wrapped in ltcodegtlt/codegt 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 comment in front of the class
  declaration.
• Methods
• Parameters to the method
• _at_param
• Return values
• _at_return
• Exceptions thrown from the method
• _at_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 _at_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 HTML tag ltcodegt 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
• You have to write the comments yourself, but
  NetBeans points out where you ought to write
  comments.
• NetBeans can active 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 employee 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/writingdoccomment
  s/index.html
• Suns 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