CSC152 2004F, Class 22: Documentation

Admin:
* Homework due and assigned.
* Math/CS Table: Mondays, Cowles North PDR
* Exam returned
  * Stop at eight hours!
  * Come talk to me with questions (1:30-3:00 today; normal times rest of week)
* When you have problems that you think you'd like to ask about later, SAVE THE CODE, even if you fix it later.

Overview:
* Why document?
* Where to document?
* Javadoc

/Claim: It is important to document your code!/
* By "document" I mean: Insert comments to reader that do not affect the actual running of your code.
* The "reader" needs to know what you're talking about
  * People who have to modify or repair your code (or both)
    * People who want to write similar code.
  * Programmers who want to use your code without modifying it.
  * Yourself, in the future (after six months, you'll have forgotten everything)
  * Yourself, now (provides easy navigability of your code and ideas)
  * People who are hopelessly lost: Figure out what everything does
  * Sam and TAs: 
    * Puts us in a better mood for grading.
    * Might allow some partial credit.  (Yeah, they were on the correct track when they wrote this, um, profanity.)
    * When Sam tries to help you fix a problem, he knows what you were actually trying to do.
   * People who want to run your program.  (An impossible task?)
* Summary:
  * Maintainers: Programmers who maintain and modify our code.
  * Reusers: Programmers who use our objects, but don't care about our implementation.
  * Developers: Programmers who try to implement our documentation (usually ourselves)
  * Evaluators: People like Sam who try to decide how wonderful your work really is
* Moral: Different kinds of documentation for different audiences.
* When should you write your documentation?
  * "As you go" (Don't document after you've written all of your code as you may have forgotten the details.)
  * Before coding.

/Where do you write documentation?/
* Everywhere.
* Usually one big README file that explains the overall structure (what classes and interfaces there are and how they relate).
  * Audience: Maintainers, Developers, Evaluators
* A summary of each class's purpose (usually at the top of the class).
  * Audience: Reusers, (and everyone else)
* Other meta-information (author, version)
  * Audience: Other programmers
* Documentation for each method (including constructors)
  * Including preconditions and postconditions [REINFORCED]
  * Including exceptions
  * Including purpose
  * Including info about parameters
  * Including info about value returned
  * Audience: Everyone
* Documentation for each field
  * Purpose
  * Type
  * Restrictions: (E.g., denominator of a fraction shouldn't be negative)
  * Audience: Anyone who wants to use those fields.  (Encapsulation says everyone except Reusers.)
* Information about tricky areas of programming that may not be immediately obvious.
  * Audience: Everyone except reusers.

Observation: Reusers should be able to see selected comments without bothering to look at our code.
* The designers of Java decided that it should be easy to generate documentation for reusers (so they don't have to see our code).
* The tool is javadoc.

(1) Open a new terminal window by clicking on the little image of the computer.
(2) Type 
	kate .bashrc
(3) Go to the end of the file and insert the following line:
	alias jdoc='/opt/IBMJava2-142/bin/javadoc -version -author -tag pre:m:"Preconditions" -tag post:m:"Postconditions"'
(4) Save the file.
(5) Quit Kate
(6) Close your terminal window.

Later
(1) Open a new terminal window.
(2) Create a directory
(3) cd to that directory
(4) Type jdoc SOMEPACKAGENAME
	jdoc rebelsky.newvec
	jdoc ahlgrenl.exam1
(5) Cross your fingers
(6) In your Web browser, open /users/YOURUSERNAME/YOURDIR/index.html
(7) Uncross your fingers (I'm impressed that you typed the stuff above with crossed fingers)