Documentation

Objective #1: Document Java source code appropriately.

• Follow our class Coding Standards for advice on documenting Java source code.
  
  
• There are three kinds of comments in Java
  • You can comment out a single line by using // as in
    
    // this is a comment
    
    or
    
    System.out.println("hello world");    // this is a comment
    
    
  • You can use a block comment to comment out a section of code over multiple lines as in
    
    /*
    This is ignored
    by the computer
    */
    
    Everything between the /* and the */ is treated as a comment.
    
    
  • Or you can use javadoc-style comments by placing a comment between /** and */ as in
    
    System.out.println("hello world"); /** This is ignored by the computer
    even though it extends over multiple lines */
    
    However, javadoc-style comments begin with /** (two asterisks) instead of /* (one asterisk) and are meant for serious comments that are used to create HTML API manuals.
    
    
• However javadoc documentation is not tested on the AP exam. Except for the header at the top of each class, you will not be required to add javadoc comments to programming assignments this school year.
• Many people include Javadoc comments though directly above the first line of each method. The first line of this comment should summarize the method. Then, on successive lines of the comment, you should list the purpose of each explicit parameter (if applicable) beginning with a @param tag. Finally, you should include a line that explains the value that is returned (if applicable) by the method. This line must begin with a @return tag.
• You can use javadoc-style comments to efficiently create an online manual for your Java classes. They can be used to create HTML help pages for the code that you create. By enclosing javadoc comments along with your source code in the appropriate places, a utility can be used that automatically creates HTML Web pages that explain your code and serve as online help. In fact, the online Java API was built from javadoc comments.
• Since the javadoc utility that creates HTML Web pages from your Javadoc comments within a class, you can include HTML tags within your Javadoc comments.