Java

INDEPENDENT TOPIC 04 – JAVADOC COMMENTS

LESSON NOTE

COMMENTS

As you should know at this point, comments are simply words that are ignored by the compiler. They serve asbin an aid to humans reading source code explaining details about the implementation.

TYPES OF COMMENTS

In Java, there are two types of comments. A single line comment starts with // where the rest of the line is then ignored. Here's an example:

int x = 5; //the x-coordinate of the object

The second type of comment is a block comment. It starts with a /* and end with a */. Everything between those two is part of the comment. This comment can be multiple lines. Here's an example"

/* The following program will get three numbers from the user and then output the sum, the product and the

difference between the numbers.

*/

public static void main(String[] args)

{

…

}

JAVA API

You should know about that Java API. It's the documentation for all Java classes maintained by Oracle. If you don't know about this site, simply google "Java API" and go take a look.

Notice how every single class has an html document for it. And that document is standard throughout.

This is the case because there is a special program that automatically generates these html documents using one's source code and special commenting within the code.

JAVADOC PROGRAM

The Javadoc program is a program that can be found inside the bin folder that is inside the Java folder (that is usually inside the Program Files folder – or wherever you installed Java to).

This program can be used to automatically generate the html files for the java documentation. And you can use it to generate similar files for your classes.

However, to use it effectively, you do need to add special comments called doc comments that are used to describe parts of your code.

DOC COMMENTS

Doc comments are special comments that are used to give specifications about the code without usually touching on implementation details. These comments are used to auto-generate the html documents that form the Java API.

Doc comments are placed inside block comments. However, instead of the /* at the start, we use /** to let the Javadoc tool know that the comment should be used by it.

To make use of the Javadoc program, we need to learn where doc comments are expected and more details about them. Let's look at a few examples:

EXAMPLE 1

Let's consider the following class that contains three functions (static methods) and no comments:

public class Util

{

public static double distance(int x1, int y1, int x2, int y2)

{

int dx = x2 - x1;

int dy = y2 - y1;

return Math.sqrt(dx*dx + dy*dy);

}

public static String initials(String first, String last)

{

String letter1 = first.substring(0,1).toUpperCase();

String letter2 = last.substring(0,1).toUpperCase();

return letter1 + ". " + letter2 + ".";

}

public static double avg(int m1, int m2, int m3, int m4)

{

return (m1+m2+m3+m4)/4.0;

}

}

Now let's add doc comments. We start off by adding a doc comment at the very top to explain what the class does. We then add a doc comment above each function.

Notice that there are extra asterisks on the middle lines. Eclipse adds them for readability.

/** This class holds a few utility functions.

*

* @author Pat Campeau

*/

public class Util

{

/**Calculates the distance between (x1,y1) and (x2,y2).

*/

public static double distance(int x1, int y1, int x2, int y2)

{

int dx = x2 - x1;

int dy = y2 - y1;

return Math.sqrt(dx*dx + dy*dy);

}

/**Returns the initials of the person with the name

* first last.

*/

public static String initials(String first, String last)

{

String letter1 = first.substring(0,1).toUpperCase();

String letter2 = last.substring(0,1).toUpperCase();

return letter1 + ". " + letter2 + ".";

}

/**Calculates the average mark for a student using the

* four marks from that students four courses.

*/

public static double avg(int m1, int m2, int m3, int m4)

{

return (m1+m2+m3+m4)/4.0;

}

}

Now that we have some doc comments added, we can use the Javadoc tool to auto-generate a Java documentation webpage for our class. (See next section to learn how to do this.)

Below you see a screen capture of part of that webpage.

USING THE JAVADOC TOOL IN ECLIPSE

First off, the Javadoc.exe program is located inside the bin folder that is inside the java folder (which is usually inside the Program Files folder or wherever you installed Java). You will need to find this file for the first time that you create Javadoc with Eclipse.

Once you have your class and all doc comments in it, you simply choose Project > Generate Javadoc…

That will bring up the following window. If this is Eclipse's first time to use Javadoc, it you will have to point it to the file (like shown in the red ellipse).

Once you hit Finish, you can find the webpage at the Destination folder (see above window).

ADDING TAGS

We can add more details to your doc comments. There are several tags that we can use to provide specific information. Tags start with the @ symbol and then the tag's name. The most common tags are probably @param and @return to describe the parameters of a method and what a method returns.

We will not go into more details here.