Class 20: Documentation and JavaDoc

Held: Friday, February 25, 2005

Summary: Today we consider issues related to the documentation of programs We also consider javadoc, a special tool for generating documentation for Java.

Related Pages:

• No eboard today!
• Reading on Javadoc.
• Lab on Javadoc.

Overview:

• Why document?
• Kinds of documentation.
• Javadoc basics.

Why Document?

• It helps you think about what you're doing.
• It helps you remember what you did.
• It gives others insight (essential in real code).
• Who are the audiences for documentation?

Where Document

• General documentation for the set of classes: Typically in a README file.
• For each class, an introductory paragraph (or paragraphs) that summarize the purpose.
• For each class, a summary of the tricky design issues.
• For each method, field, and constructor, a similar paragraph.
• Within each method, to explain the code.
  • General structure.
  • Tricky ideas.

Javadoc

• Javadoc is Java's cool tool for generating some documentation for the people who use your classes.
• Every comment that has the form /** ... */ that precedes something (class, method, field, constructor) is a doc comment and can be included in the generated documentation.
• Use the following command to generate your documentation

  /opt/IBMJava2-142/bin/javadoc -author -version -tag pre:m:"Preconditions" -tag post:m:"Postconditions" package1 package2
  

• We'll do a few samples.
• The @author tag gives authors.
• The @version tag gives the version.
• The @param name tag describes parameters.
• The @exception type tag describes exceptions.
• The @return tag describes return values.
• The @pre tag describes preconditions.
• The @post tag describes postconditions.

Lab

• Do the lab.