In this mini-lab, you will look at the javadoc comments that precede method definitions, including how they specify what parameters a method expects to receive and what type of value (if any) a method returns.

Exploring Javadoc Comments

In this mini-lab, you will look at the javadoc comments in the Clock class from the Timestamp Mini-Lab or the TalkingRobot project, and compare the comments in the class to its class documentation. (The class documentation for a class is the page you see when you choose Documentation rather than Source Code in the upper-right corner of a BlueJ editing window.) Class documentation is generated from source code, similar to how compiled code that the computer can read is generated from source code.

Remember that javadoc comments are ones that start with a double-asterisk (/**).

• Read the Java source files for the Clock class, which you can find in either the Timestamp project or the TalkingRobot. Use the pull-down menu in the upper-right corner of the editor window to see how you can switch between the source code and the class documentation for the class.
   
• Download the template file for this assignment (Markdown format) and, using an appropriate editor, write your answers to the following Analysis Questions about javadoc comments and class documentation.
  • In the documentation page, where does the general class information (the information that comes before the Constructor Summary) come from?
  • How does the use of the HTML <br> (line-break) tag affect the look of the class documentation page? What happens if you remove them?
  • What effect do the Javadoc @author and @version tags have?
  • Where does the information in the Constructor Summary come from? Where does the information in the Method Summary for the addTestCase method come from?
  • Is there a difference between the Constructor Summary and the Constructor Detail information?
  • What is the difference between the Method Summary and Method Detail information for the addTestCase method? Where does the extra information in the Detail come from? What about for the getHH method: what is the difference between the Summary and Detail information, and where does the extra information come from?
  • What about for the changeTime method: what is the difference between the Summary and Detail information? What is your hypothesis for what the javadoc tool chooses to include in the Summary vs what it includes in the Detail? Temporarily modify the javadoc comment for some other method to test your hypothesis.
  • List the javadoc tags (keywords in javadoc comments starting with @) you've seen in this class, along with what affect they have on the generated Documentation, and where.

Submit your Analysis Questions to Kit.