Lab Exercise #8
for lab meeting Tuesday, Nov. 22, 2005
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 a course-specific class
First let's take a look at how javadoc does its thing. In your ssh
window, bring mbf/Screen.java
into the editor, and look carefully at
the comments for each method. Now in your browser, go to
www.seas.gwu.edu/~csci53/documents,
and then click on Screen. Compare
the javadoc pages with the Java source code.
Now let's try actually using javadoc. Since javadoc generates web
documents,
you'll have to use your own SEASCF personal website to use it
meaningfully.
To do this, you're going to
- annotate a course-specific class with the special javadoc
comments
- copy this annotated class over to your personal SEASCF website
- log into your website and run javadoc
- browse the resulting documentation
- 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 shell name of
the machine SEASCF
has allocated to student websites. Use your regular SEASCF userid and
password
to log in to both computers.
- 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.
- In your public_html directory, create a new directory called csci53docs.
Type
mkdir csci53docs
and then move to this new subdirectory. - Now go back to your hobbes
window. Move to your csci53
directory,
and use vi to add javadoc comments to each of the methods in RobustInput
class. Just above the code for each method, add these lines:
/**
* (a brief description of the method goes here)
*/
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. - Now you'll move this file over to cobweb
using the ncftp
file-transfer
client. Let's say your userid is george. Type
ncftp -u george tangle
and enter your password when prompted. Once you get to cobweb, move
to public_html/csci53docs. Then transfer the file by typing
put RobustInput.java
then quit ncftp
quit
- Now you are ready to run javadoc. Go back to your cobweb
window
and type
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. - Now you need to make these files readable from a
browser, by
changing the
Unix permissions. First look at the existing pemissions: type
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
- Now you can go back to your Netscape window, and go to your
website at
http://student.seas.gwu.edu/~george/csci53docs
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 4: Using javadoc in the rest of the course, to document your
project class files
Now you can use javadoc to document your own classes!
(end of lab)
