Code Documentation

Java comes with a powerful tool called Javadoc that scans code and creates documentation.

Effectively documenting our code has several benefits:

• Everyone on the team who does programming work can better understand all the code
• Months later, when someone comes back to update the code, that person will be able to understand it more quickly
• When the code is publicly released, documentation will help people outside the team understand it, learn from it, and use it.

You can generate this documentation in NetBeans by going to the Run menu and selecting "Generate Javadoc (your project name)".

Before you can create this documentation and use it, you have to write documentation comments in your code that describe what it does. These are what Javadoc uses to make documentation.

Documentation comments can be applied to:

• Methods, to describe what each method does, what input parameters it takes, and what it returns
• Class member variables and constants, to describe what each represents or does
• Classes, to describe what each does and what uses it

Adding these comments in NetBeans is easy:

1. Put the cursor on the line above the thing you want to document

2. Type "/**". This designates the start of a documentation comment

3. Press return. NetBeans will automatically add a * at the beginning of the next line and a */ on the line after that to close the comment block.

Now you have a comment block that looks like this:

/**
 * 
 */

That second line, starting with a *, is where you type a description of what that class, variable, constant, or method does.

If you're writing a documentation comment for a method that has at least one parameter or returns something (not void), the automatically generated comment block will have extra things, like this:

/**
 * 
 * @param alliance 
 * @return 
 */

The "@param alliance" tag indicates that the method has a parameter named "alliance". Right after the word "alliance", on the same line, type a description of what that parameter should be and what will be done with it. Be sure that there's a space between the word "alliance" and your description.

The "@return" tag indicates that the method returns something. That's where you should type a description of what the method returns. Again, ensure that there's a space after "@return".

When NetBeans generates a file for a new Java class, it adds a documentation comment right before the class declaration that looks like this:

/**
 *
 * @author 
 */

By default, NetBeans puts your account username after the @author tag. You may want to change it to your real name to give yourself credit for creating that class.