Lab 5: Javadoc

Purpose: In this lab, you will practice using Java's javadoc documentation generator. The lab will also give you some experience with some simple Unix commands.

Preliminaries

In Java's object-oriented model, programs are collections of communicating objects. One advantage of this model is that it is possible to reuse an object in multiple programs. However, if we are to reuse objects, it is important that the behavior of the objects be clearly and uniformly documented.

Java provides a standard comment syntax for describing such behavior. We call the comments designed for general use descriptions javadoc comments. The standard Java development kit also provides a program for converting those comments into useful web pages.

Unix Commands

In order to complete this lab (and to prepare yourself for future work on our Unix machines) you'll need to master a wider variety of Unix commands.

Directories

Unix permits you to create directories, which are similar to the folders you find on Macintosh or Wintel workstations. To create a new directory, use
% mkdir dirname

Unix keeps track of your current working directory. When you type a command, such as jc file, Unix looks for files in the current working directory. You can switch to another directory with
% cd dirname
You can move up one level in the directory hierarchy (up to the "parent directory") with
% cd ..
You can change to your home directory with
% cd ~
or
% cd /home/username

If you know the full set of intermediate directories from your home to a particular directory, you can refer to that directory by separating everything by a slash. For example, my SimpleInput.java file can be found in the directory /home/rebelsky/lib/Java/rebelsky/io.

You can move files from directory to directory with the mv command. The basic syntax is
% mv filename directory

I'd strongly recommend that you create a separate directory for each class and project you work on. You may want to move your old 151 files to a 151 directory.

Protection

Like many multi-user operating system, Unix provides a system for protecting your files and directories. In general, Unix breaks the world into three categories,

• the owner of the file ("user")
• people in a similar category ("group")
• everyone else ("other")

Unix also segments the types of protection you can apply to a file:

• read: someone can look at the file
• write: someone can change the file
• execute: someone can execute the file (usually reserved for programs)

Unix applies similar protections to directories:

• read: someone can determine the contents of the directory
• write: someone can add files to the directory
• execute: someone can access the files in the directory

You can find out the protections that are applied to a file with
% ls -l file
You can find out the protections that are applied to a directory with
% ls -ld dir

You can change these protections with the chmod command. The form is
% chmod whohowwhat

• who can be any combination of u (user), g (group), and o (other).
• how can be + (add permission), - (remove permission) or = (set permission).
• what can be any combination of r (read), w (write), and x (execute).

For example, to give everyone permission to read a file, I'd use
% chmod ugo+r file
Similarly, to remove write permission from "everyone else", I'd u se
% chmod o-w file

In general, you should give everyone execute permission for your home directory (chmod go+x /home/user). I'll admit to being a proponent of open files, so I'd recommend you make at least one publically accessible directory.

Javadoc'ing your programs

Javadoc, Sun's Java documentation generator, creates HTML files which are accessible on the World-Wide Web. The tradition on our Unix machines is that all your web files should be in the directory /home/user/public_html, which must be world-readable and world-executable. If you don't already have such a directory, create one. You may want to make a subdirectory for your Java docs (so that when you build other HTML pages they can be separated from your Java docs).

In order for the Java documentation to be readable, you'll need to copy a set of images to whichever directory you'll be using for your documentation. Change to that directory and type
% /home/rebelsky/bin/example images

You are now ready to build your Java docs. Change to whichever directory you're using for your documentation and type
% /home/rebelsky/bin/jdoc -author -version File.java
This will create the HTML file File.html (as well as index.html and packages.html). Move that file to your public_html directory (or appropriate subdirectory).

In Netscape, you can then view the HTML by using the URL "http://www.math.grin.edu/~user/File.html". See what your HTML looks like.

If you still have time, you may want to add appropriate comments to your Java source code and re-javadoc the file. You can gain some control over the appearance of the documentation by appropriate use of HTML codes.

• <strong>stuff</strong> strongly emphasizes stuff (most typically, making it bold).
• <em>stuff</em> emphasizes stuff (most typically, making it italic).
• <p> separates paragraphs.
• <br> insets a break (a carriage return).

References

You can find more information on javadoc at http://java.sun.com/products/jdk/javadoc/writingdoccomments.html http://www.math.grin.edu/~rebelsky/jdk1.1.3/docs/tooldocs/solaris/javadoc.html http://java.sun.com/docs/books/jls/html/18.doc.html