Generating HTML

In the homework assignments, a portion of the points will be designated for writing Javadoc-style comments as in the previous example. Although we don't require you to actually generate the html for homework submission, we'd like you to try it at least once in lab, so that you can see why the exact format of Javadoc-style comments is valuable.

The JDK includes a tool that will convert the specially formatted comments into html pages like the online Java API documentation. We can run it easily from Eclipse.

  1. Highlight the "project2" project, go to the Project menu, and run Generate Javadoc.... A dialog appears. Most of the default settings are fine, but check the next three items.
  2. The project2 project should be checked.
  3. The "Javadoc command:" field should contain a path to a program called javadoc, similar to the following: 
    C:\Program Files\AdoptOpenJDK\jdk11.0.8.10-hotspot\bin\javadoc.exe
    on Windows, or 
    /Library/Java/JavaVirtualMachines/adoptopenjdk-11.jdk/Contents/Home/bin/javadoc
    on a Mac.

    The paths above show the default installation locations used by the AdoptOpenJDK installers for JDK 11 (exact version numbers may vary). If you used a different installation, you may see a different path. In some cases, you may need to click the Configure button and navigate to the javadoc executable on your computer.

    If you are not sure, feel free to ask your TA to help you find the correct path. Then click Finish.

  4. In the "Destination" field, make sure you see an absolute path into your your workspace, it should be similar to: 
    U:\cs227\workspace\project2\lab2\doc
    or 
    /Users/username/Documents/cs227/workspace/project2/lab2/doc
    on a Mac, depending on exactly how you named your workspace directory.
  5. After the javadoc tool runs (it will produce some console output) a webpage containing the documentation is created inside your project folder. You can expand the directory doc in the Package Explorer and right-click on index.html to view the page in a web browser within Eclipse. (If you'd prefer to use a traditional web browser, open the file through File Explorer.) Nice, huh?

Compare the generated webpage to the documentation in the source code. Try making some changes and see where the changes appear in the html. What effect do the @return and @param have?

If you have trouble, your TA is there to help.