Five parts of documentation for object-oriented code should be

1. An Object Model example Structure Charts (Object Models) and some tools to build them

2. Object documentation Abstract Data Types (ADTs) This particular information is very abstract...I use it in my Data Structures course. Nonetheless, it is still informative if you can get past the abstractions. Specifically, an object's methods should have documentation about its needs ( PRE conditions), its purpose and what a user can expect from a class and its methods (POST conditions). This provides a sort of contract for users of your code. For more clarity. I also have a small example illustrating need.
   See javadoc for how to have the ADT information be inline and then create nice API-like web pages to document your code. All it takes is inline documentation directly before each method that looks like:
   /** * PRE: stuff <br> * POST: stuff <br> */
   and then when you run javac to compile, also run javadoc on the .java file. It will make a classname.html for each class in your file. Make sure to put the <br> tags there to tell html to break to the next line. For private classes, see my java page.
   Or, for a comprehensive look at javadoc see Suns "How to Write Doc Comments for the Javadoc Tool"
   Also see making webpages below for examples

3. In-line documentation

4. Sources: If you used someone else's classes (or code) as a part of your lab, document this. It is OK to use other work but in your documentation, be clear on what is yours and what is theirs. Otherwise, it is plagiarism.

5. A README (especially for applications) to tell the user how to run your program

In general, all of this (and the README discussed below )

Offsite people, again, because of firewalls, etc, I suggest you get an account here and make a web page at our site

Do not send me the equivalent of a README file in the mail. In fact, in reality, I should not need to get any mail from you regarding lab submissions since you should have registered them and any information should be at the ftp site or on the web page. Except if you are taking a video course and I do not have any other way of knowing when you might be submitting materials

Java and portability. Yes, Java is machine independent, but filing systems are not. I should not have to manipulate directories because you used a package name but did not send it to me in the same structure. Nor should I have to look for classes with main() in them. Nor should I have to change file names so there are no spaces in them, edit capitals (case specific), or add things to classpaths that you did not mention were needed.

For applications (I need to download to run), to make sure that I see the same files and directory structures as you, you should submit your labs (with any classes needed to run it that are not in the JDK) using a jar. For the java programming classes, the last java lab submission is illustrated at http://www.ecst.csuchico.edu/~amk/foo/advjava/notes/CSsubmission.html . You should use jars for all the java labs that are not runnable from a web page (and you might want to use them there too to get used to them for applets), but you will not need to have multiple jars for labs other than ones that run on more than one machine (e.g. client/server, RMI, etc).

A Beginner's Guide to HTML (original page is gone but this has links to three nice pages..including tutorials pages with a beginner's document with basic links
The Advanced HTML index
HTML tutorial and references

Finally, related to the above. It works very nice when you have a web page with links to all of your stuff, so I don't have to open a million things, all I have to do is follow your links. Here is a Java example. In this example, I was showing people how to take your application and make it into an applet (if you had a main() that was not ridiculous). Here is another example for HelloWorld. This one shows how to use javadoc for documentation, (this is as easy as using /** and */ for documentation - look in the source to see the exact file and what it generated) but this example is missing any object model and a link to the .jar with all the files.

I have links to these here so you can look under View at DocumentSource or PageSource and see how easy it is to make a web page with all your stuff.

Note that even if you have an application, you can make a web page with all of your documentation and information, and then make a .jar file link for me to download. See this guide page and this jar tip page for jar information. Even though this page talks about using jar files for applets, you could use it for an application since it is similar to providing a .zip file containing all your classes. Note this is also handy to transport anonymous classes with the dollar sign problem.

For those of you behind firewalls, get an account here and make your page here.

The best way to see if your submission is OK...May I make a suggestion? Give a link to your program submission to some stranger, along with the code - not on your machine - and tell them to look at it. Just stand there and don't say a word about what to do. If they have any questions, this material should be somewhere in a README or documentation so that I don't have the same question. Please realize that yours is not the only one I am looking at and you are not standing over my shoulder.