What is Javadoc?

Java has three types of comments.

//  This is a one-line comment.

/*  
this is a multiline comment.
*/

/**  
this is a Javadoc comment.
*/

Javadoc allows you to have an HTML page that integrates nicely into the general Java API reference. It's pretty amazing.

When we write code, we write it for two audiences. One is the compiler. It turns your code into something executable.

The other is your colleagues in a professional environment. Often they want to use your classes and not have to puzzle through your rococo creative code.

It is common for a programmer to create a class or a suite of related classes designed to perform a related set of tasks. These classes would be compressed into a .jar file, which the clients could compile into their code.

What the client needs to know is stuff like this.

• What do instances of this class do?
• Does the class spawn mutable or immutable objects?
• What arguments does each method need?
• What does each method return?
• What is the meaning of any static constants or quantities?
• Do any of the methods have the potential to throw an exception? If so, what can cause this lamentable event to occur?

Javadoc creates HTML to hold documentation that answers these questions.

Setting up for Javadoc

1. Make sure your code compiles
2. In the same folder as your program, make a folder called doc
3. Run the command javadoc -d doc YourGreatProgram.java
4. From your browser, select Open File... and navigate to the index.html file in the folder doc.

You will be able to view your Javadoc page.

Get yesterday's BigFraction code and we are going to javadoc it.