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: inline comments, block comments, and javadoc comments
  
  
• inline comments
  
  You can comment out a single line by using two forward slashes // as in
  
  // this is a comment
  
  or
  
  System.out.println("hello world");    // this is a comment
  
  Anything to the right of the comment marker is treated as a comment.
  
  
• block comments
  
  You can use a block comment to comment out a section of code over multiple lines as in
  
  /*
  This is ignored
  by the computer
  */
  
  or
  
  System.out.println("hello world"); /* This is ignored by the computer
  even though it extends over multiple lines */
  
  Everything between the /* and the */ is treated as a comment. This type of comment is handy when you need to comment out many lines of code such as when you are debugging a section of code.
  
  
• There are menu commands in Eclipse that make it easy to comment out one or more lines of code. The Source/Toggle Comment and other submenu commands under the Source menu command are helpful.
  
  
• javadoc comments
  
  You create a javadoc comment using two asterisks at the beginning of the comment as in         /** this is a comment */
  
  This type of comment also works like the block comment explained above as in
  
  /**
  This is ignored
  by the computer
  */
  
  However, javadoc comments are mainly meant to be used to create API documentation web pages that explain your source code. By enclosing javadoc comments along with your source code in the appropriate places, an IDE like Eclipse can be used to automatically create web pages that explain your code and serve as online help. In fact, the online Java API was built from javadoc comments.
  
  
• You will not be expected to write javadoc comments on the AP exam. You may be expected to identify the difference between javadoc and other types of comments though in multiple choice questions. Except for the documentation header at the top of each class that should look like this
  
  /**
   * ASCIIArt
   * @author John Doe Per 1
   */
  
  you will not be required to add any other javadoc comments to programming assignments in this course.
  
  
• Follow this tutorial to learn how to easily create your own API documentation web page by using javadoc comments.