CS 139 Algorithm Development
Lab10A: Using Javadoc and APIs

Background

Objectives

• generate documentation pages for their programming assignments
• show how to run Javadoc, both from the command line and an IDE
• navigate and interpret Javadoc pages in the Java API Specification

Key Terms

API : Application Programming Interface. Javadoc summarizes the API for a class by listing the methods that can be called and what parameters they require.

Submission

1. Run Javadoc on your PA3 source code, and submit the files Yahtzee.html and Yahtzee_Test.html via Blackboard. Please attach these files separately; do not zip them.


2. Complete the CodingBat exercises indicated below, using the Java API Specification as directed. You may need to look for methods you have never used before to solve these problems.

Part 1: Java Source

Throughout the semester, you have been using classes that come with the Java Platform, Standard Edition or Java SE for short. Technically speaking, code like System.out.println() is not part of the Java language, but rather part of the Java library. Did you know that the source code for Java SE is freely available? Have you ever wondered what "real world" Java code looks like? If you haven't already, you should take a look! Here are several Java SE classes we have used thus far:

As you can see, it's fairly difficult to read the source code to get an idea of what's going on. For example, String.java is over 3,000 lines! But you all know about methods like String.equals() and String.length() -- you don't need to understand how they're implemented in order to use them.

By the way, classes which belong to java.lang do not require an import statement in your programs. Because these classes are used so often, java.lang.* is automatically imported by the compiler.

Part 2: Hello Javadoc!

Javadoc was created to give programmers a high-level summary of what methods are in a class, without having to look at the source code. For example, compare the java version and the html version of each class in the above table. Find the source code for the String.length() method. How many lines of code are in this method? How many lines are in the Javadoc comment?

Now let's run Javadoc on your own code. To get started, download a copy of your PA3 submission from Web-CAT if you don't have the files with you. You should have Yahtzee.java, Yahtzee_Test.java, and Dice.java in the same directory.

1. Open a terminal in the directory of your PA3 files.


2. Run the command: javadoc -d doc *.java
   (The -d option specifies an output directory.)


3. Open the file doc/index.html in a web browser.


4. If any of your methods are missing documentation, go back and write Javadoc comments in your source code!

It's good to know how to run Javadoc from the command line, because there are a lot more options. You can also run Javadoc directly from most IDEs, for example:

DrJava

5. Open Yahtzee.java, Yahtzee_Test.java, and Dice.java in DrJava.


6. Click the Javadoc button on the toolbar.


7. DrJava will prompt you for the output directory (i.e., the -d option) before generating the html files.


8. DrJava also opens an internal web browser for you to view the results.

jGRASP

5. Open Yahtzee.java, Yahtzee_Test.java, and Dice.java in jGRASP.


6. Click the Javadoc button on the toolbar. (It's the icon that looks like an open book.)


7. JGrasp will open a web browser for you to view the results.


8. Results will be found in a user directory named .jgrasp_settings/doc_tmp. You can always move them to a more permanent directory.

Part 3: CodingBat

• String-2 endOther


• String-2 getSandwich


• Logic-2 evenlySpaced

Part 4: Checkstyle

How would you like to get 100% on your next PA? Most students are getting 70/70 on correctness, but quite a few are losing up to 20 points on style. There are a number of free tools available that analyze Java source code, including Checkstyle. This command-line utility not only reports style violations, but also identifies common programming mistakes.

To get started, download the following files to your PA directory:

• checkstyle-5.6-all.jar - command line tool


• cs139.xml - configuration file for CS 139

Use the following command to run Checkstyle:

java -jar checkstyle-5.6-all.jar -c cs139.xml *.java

The output indicates the file and line number of each problem. For example, "Yahtzee.java:93:5: Missing a Javadoc comment" refers to a method starting on line 93, column 5 of Yahtzee.java.