Section 3 with Remik (rz33@cornell.edu) 
Meeting #6 Notes
********************************************************
Administrivia:  Hw#2 deadline extended to Friday
		CS211 Prelim Thursday night
Review:		Commenting in Java & using javadoc

SElf-Documenting Code
********************************************************
	If you've ever read someone else's code, I bet it 
wasn't easy.  As programmers, we need to make our code
as understandable as possible for others and ourselves
(try to read your own program 1 year after writing it!). 
	Help us all by commenting as much as possible.
To start, you can make your code self-documented.

Example:
	int numHistogramBins, frameRate;  // and not int n, f;

This notion can be extended to methods and classes as
well, but our focus will be on a different type of
documenting style.  BTW, 2 classical styles of variable 
naming are Hungarian and Camelback (DON'T USE THESE!).

Hungarian notation:
	int iNumHistogramBins, iFrameRate;
Camelback:
	int NUMhISTOGRAMbINS, FRAMErATE;


Commenting for javadoc - A Mechanism for free HTML Docs.
*********************************************************
	The basic multi-line comment block in Java looks
as follows:

	/** This is my own little comment. It extends
	  * multiple lines.
	  *      Using '*' also preserves whitespace, so
	  *      I can make funny diagrams like  
	  *		\root
	  *		 |
	  *		 `-->\src
	  */

The javadoc tool looks for comment blocks in 
specific places. They must be placed before:
	* classes
	* interfaces
	* methods
	* fields (class variables)
	
To be yet more descriptive, and to have your HTML documents
look cooler, there a few keywords allowed.  Here is an
extensive example with each keyword prepended with @. Basically
each keyword is used to describe components, such as 
method parameters (@param), the meaning of return values 
(@return), etc.

Example:
	/** Generates tokens and stores them in an 
	 *  abstract syntax tree following the specification
	 *  of language X.
	 *
	 *  @author Remik Ziemlinski, and Friends
	 *  @version 1.1
	 */
	public class Parser {
		/** This guy handles all the yucky character
		    reading stuff. */			
		private LexicalAnalyzer lexicalAnalyzer;

		/** Invokes parsing.
		  *
		  * @param fileIn this acts as the program's file
		  * @return true if there are no warnings about syntax
		  * @throws causes an exception if syntax is wrong
		  */
		public boolean parse(CS211In fileIn) throws Exception {...}
	}


If this class was saved as c:\src\Parser.java, and I wanted the HTML
files to be put in the destination c:\html, I would generate the
documentation as follows:

c:\cd src
c:\src\javadoc -d c:\html Parser.java

For more info., see the JDK Tool Documentation (www.java.sun.com).