JMU
Lab: Skills - Documentation Tools


Instructions: Answer as many of the following questions as you can during the lab period. If you are unable to complete the assignment during the lab period it is strongly recommended that you complete it on your own.

Getting Ready: Before going any further, you should:

  1. Make a directory for this lab.
  2. Setup your development environment.
  3. Download the following files:
    Track.java
    AudioTrack.java
    Playlist.java
    jmucs.css
    jmucs.gif
    worksheet.txt
    to your working directory. (In most browsers, the easiest way to do this is by right-clicking on each of the links above.)

1. javadoc Basics: javadoc is a tool that creates WWW pages from the comments in Java source files. javadoc comments begin with /** and end with */. (Lines in between the start and end markers may begin with a * or not, as you prefer.) This part of the lab will help you get started with javadoc.
  1. Open the files AudioTrack.java, Playlist.java, and Track.java in your editor. Briefly review the source code.
  2. Open a terminal/shell window and make the directory you created for this lab the current directory.
  3. Enter the command: 
        javadoc *.java
  4. Open the file index.html with the WWW browser of your choice (e.g., Internet Explorer, Firefox). This will probably involve something like clicking on File and pulling down to Open or Open File.
  5. What do you see?
  6. Click on the Index link on the top of the main frame.
  7. What do you see?
  8. Click on the link for the Track class.
  9. What methods are included?
  10. Why do you think the method padWith0() is not included in the page that was generated for the Track class.
  11. Why is there no link to the documentation for the String class?
  12. Add the following comment: 

        /**
     * Explicit Value Constructor
     */

    above every constructor in all of the classes.

  13. Add an appropriate comment above all of the other methods in all of the classes.
  14. Enter the command: 
        javadoc *.java
  15. Open the file index.html with the WWW browser of your choice (e.g., Internet Explorer, Firefox).
  16. What changed? (Be careful -- look everywhere.)
2. javadoc Tags: You can include a variety of special javadoc tags in your comments. This part of the lab will help you understand what they do.
  1. Add the following: 

     *
 * @version 1.0
 * @author  Your Name Here

    to the block comment at the top of all of the classes (replacing Your Name Here with your name).

  2. Add the following: 

         *
     * @param artist          The name of the artist
     * @param title           The title of the AudioTrack
     * @param hours           The number of hours in the length
     * @param minutes         The number of minutes in the length
     * @param seconds         The number of seconds in the length
     * @param normalChannels  The number of normal channels
     * @param centerChannels  The number of center channels

    to the block comment at the top of the constructor in the AudioTrack class.

  3. Add the following: 

         *
     * @return  A String representation of the channels (e.g., "5.1")

    to the block comment at the top of the getChannels() method AudioTrack class.

  4. Enter the command: 
        javadoc *.java
  5. Open the file index.html with the WWW browser of your choice (e.g., Internet Explorer, Firefox).
  6. What changed?
  7. Add appropriate tags to each method and constructor in the other two classes.
3. Customizing javadoc Pages: It is possible to customize the pages generated by javadoc in a variety of different ways. This part of the lab will give you some experience with a few of them.
  1. Edit a file named options (with no file extension), add the following line to it: 
    -bottom "James Madison University, Department of Computer Science"

    and save the file. (Hint: Make sure the file was saved as options and not, say, options.txt.)

  2. Enter the command: 
        javadoc @options *.java
  3. Open the file index.html with the WWW browser of your choice (e.g., Internet Explorer, Firefox).
  4. What changed?
  5. Add the lines: 
    -footer "<img src='jmucs.gif'/>"
-header  "<img src='jmucs.gif'/>"

    to the file named options and save it.

  6. Enter the command: 
        javadoc @options *.java
  7. Open the file index.html with the WWW browser of your choice (e.g., Internet Explorer, Firefox).
  8. What changed?
  9. Add the line 
    -stylesheetfile "jmucs.css"

    to the file named options and save it.

  10. Enter the command: 
        javadoc @options *.java
  11. Open the file index.html with the WWW browser of your choice (e.g., Internet Explorer, Firefox).
  12. What changed?
Department of Computer Science

Copyright 2011