In the previous lesson we looked at recommended overrides from the Object class,
Documentation, testing, and debugging
Java provides a built-in tool to help you document your classes. NetBeans incorporates the JUnit testing tool and a debugging tool.
In this section you will learn:
- How to document your classes and packages
- How to test your classes and application
- How to debug your classes
Class & package documentation
In an earlier section, you saw the web-based documentation of the Java APIs, known as Javadoc. This was generated using a Java supplied tool of the same name, and which you can use to generate documentation for your own classes, too.
To see this in action, you will return to the Email utility class created previously. You need to insert multi-line comments in a particular format which the Javadoc tool looks for, where these comments immediately precede the class header, constructor or method being documented.
Insert the following lines just before the class header:
- Note that there are two asterisks after the slash character on the first line, which indicates to Javadoc that this is a documentation comment block
- You can embed HTML formatting tags, such as
<code></code>above
You should document the constructor:
- The
@paramannotation is used for each argument (also known as parameter), made up of three parts separated by spaces: @param– the annotation codeemail– the argument variable name- An explanation of the argument
- The
@throwsannotation is used for each exception which could be thrown, also made up of three parts. Because the constructor invokes thevalidate()method which throwsIllegalArgumentExceptionyou should document this here. ANullPointerExceptioncould also be thrown from thevalidate()method if theemailvalue isnullwhen it attempts to invoke a method upon it.
Here is the documentation for the getEmail() method:
- The
@returnannotation describes the value which will be returned from this method.
The getLocalPart() method could be documented as follows:
The getDomainPart() method would be very similar:
As would the toString() method:
For the equals() method:
For the hashCode() method:
For the compareTo() method:
Because the validate() method is private, the Javadoc tool will ignore any comments you supply. This is because the purpose of Javadoc is to tell you which constructors and methods are able to be invoked from client objects, and private members are by definition not available externally to the class in which they are defined. However, it can still be useful for other programmers reading your source code so a Javadoc will still be written:
With the Javadoc comments in place, right-click the Utilities node in the Projects window and select Generate Javadoc. A browser window should appear, as follows:
You can see the comment line next to the Email class. Click on its hyperlink to see the full documentation for the class:
You can scroll down to see the detailed documentation for the constructor and methods.
You can provide an overview of the classes in an entire package by creating an HTML file in the package called package.html, which needs to be in standard HTML format. Right-click the com.example.util package node and select New Other, then select Other from the Categories list and HTML File from the File Types list. Click Next> and then enter package as the File Name and click Finish. A template is built for you, and you only need to provide the <body> text:
Regenerate the Javadoc to see the package description appear on the initial page.
More detail about Javadoc can be found at the following link:
Purely for reasons of space, no further Javadoc comments will appear in this course.
In the next lesson you will learn how to test a class using JUnit.