School of Engineering and Applied Science
Department of Computer Science
CSci 133 -- Introduction to Software Development
http://www.seas.gwu.edu/~csci133/fall03
Prof. Michael B. Feldman
mfeldman@gwu.edu

Lab Exercise #5
for lab meeting Wednesday, Oct. 1, 2003

The purpose of this lab is to explore javadoc, the Java class documentation tool that's provided by Sun, and used there to document the Java standard libraries (Application Programmer Interfaces or API's). It's also used by many Java users.

Part 1: Visiting the Sun website to explore the APIs

Let's go to the Sun website and look at the "official" documentation of a few standard classes we've encountered in the course.

Open a Netscape window and go to http://java.sun.com. At the right side of this page, you'll see a link to J2SE1.4 APIs. Click on this link. You'll see 3 frames: the ones on the left are indexes to the packages and classes; the large window shows the details of a particular package or class.

In the class index, scroll down to Math and click. Now in the large window, scroll down to the method summary; you'll start to see some familiar methods. Try to make some sense of all the stuff at the top of the window; it isn't necessary to really understand it at this point.

Now do the same with Random and String. The objective here is not necessarily to understand all the details of each class and each method, but rather to just familiarize yourself with how Sun documents these things.

Part 2: Using javadoc to document some course-specific classes

Now let's try actually using javadoc. Since javadoc generates web documents, you'll have to use your SEASCF personal website to use it meaningfully. To do this, you're going to
  1. Let's get your website ready. Open an ssh window to hobbes, and a second ssh window to cobweb.seas.gwu.edu. This is the machine SEASCF has allocated to student websites. Use your regular SEASCF userid and password to log in to both computers.
  2. In your cobweb window, list the directory. You'll see a subdirectory called public_html. Move to this directory; it is where your public web documents reside.
  3. In your public_html directory, create a new directory called csci133docs. Type
    mkdir csci133docs

    4. and then move to this new subdirectory.
  4. Now go back to your hobbes window. Move to your csci133 directory, and use vi to add javadoc comments to each of the methods in the jss2/ArrayBag class. Just above the code for each method, add these lines:

    5. /**
    *  write a 1-line description of the method
    */

    The /* and */ comment markers are those of Java's C ancestor. They are legal in Java, but they are used mostly for javadoc annotations. /* followed by an extra * is recognized by javadoc to mean "begin a javadoc annotation". Add similar lines to the other two methods, save the file, and quit the editor.
  5. Now you'll move this file over to cobweb using the ncftp file-transfer client. Let's say your userid is george. Type

    6. ncftp -u george tangle
    and enter your password when prompted. Once you get to cobweb, move to public_html/csci133docs. Then transfer the file by typing
    put jss2/ArrayBag.java
    then quit ncftp
    quit
     
  6. Now you are ready to run javadoc. Go back to your cobweb window and type

    7. javadoc *.java
    and observe the messages. When javadoc is done, you should have a set of html files, as well as one or more subdirectories containing more html files.
  7. Now you need to make these files readable from a browser, by changing the Unix permissions. First look at the existing pemissions: type

    8. ls -l
    you'll see a bunch of codes next to each file name, something like
    -rw-------   1 george user  685 Nov  5 00:04 allclasses-frame.html

    The codes on the left indicate that on the html files, you (the user) have read/write permissions and nobody else has any. On the Java file, others have read access. Now type

    chmod -Rf 755 *

    which means "change the mode (permissions) on all files to "everyone can read and execute and I can also delete". List the directory again; now it looks like
    -rwxr-xr-x   1 george user  685 Nov  5 00:04 allclasses-frame.html

  8. Now you can go back to your Netscape window, and go to your website at

    9. http://student.seas.gwu.edu/~george/csci133docs
    Browse around and see what javadoc put there.
This is all rather involved and a bit tricky; this is mostly because, for security reasons, SEASCF put the web server, cobweb/tangle, on a different computer from the regular server,hobbes. It's a lot easier once you've done it a few times.

Part 3: Using javadoc to document your project class files

Now you can use javadoc to document your own classes!

(end of lab)