Java programming course: 10.1 Documentation, testing, and debugging

In the previous lesson we looked at recommended overrides from the Object class,

• Previous lesson: 9.3 Recommended overrides from the Object class
• Course contents

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:

package com.example.util;

/**
 * The Email class represents an immutable email address
 * in the format <code>local-part@domain-part</code>.
 */
public final class Email implements Comparable<Email> {
 

• 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:

package com.example.util;

/**
 * The Email class represents an immutable email address
 * in the format <code>local-part@domain-part</code>.
 */
public final class Email implements Comparable<Email> {
    
    private String email;

    /**
     * Constructs an <code>Email</code> object with the specified address.
     * @param email the full email address
     * @throws <code>IllegalArgumentException</code> if the argument is not a valid email.
     * @throws <code>NullPointerException</code> if the argument is <code>null</code>
     */
    public Email(String email) {
 

• The @param annotation is used for each argument (also known as parameter), made up of three parts separated by spaces:
• @param – the annotation code
• email – the argument variable name
• An explanation of the argument
• The @throws annotation is used for each exception which could be thrown, also made up of three parts. Because the constructor invokes the validate() method which throws IllegalArgumentException you should document this here. A NullPointerException could also be thrown from the validate() method if the email value is null when it attempts to invoke a method upon it.

Here is the documentation for the getEmail() method:

/**
 * Returns the full email address.
 * @return the email address
 */
public String getEmail() {
 

• The @return annotation describes the value which will be returned from this method.

The getLocalPart() method could be documented as follows:

/**
 * Returns the local-part of the email address,
 * that is, the part before the @ character.
 * @return the email local-part
 */
public String getLocalPart() {
 

The getDomainPart() method would be very similar:

/**
 * Returns the domain-part of the email address,
 * that is, the part after the @ character.
 * @return the email domain-part
 */
public String getDomainPart() {
 

As would the toString() method:

/**
 * Returns the full email address.
 * @return the email address
 */
@Override
public String toString() {
 

For the equals() method:

/**
 * Compares this email to the specified object.
 * Returns <code>true> if the argument is not <code>null</code>
 * and is an <code>Email</code> object with the same email address.
 * @param other the object to compare this <code>Email</code>against.
 * @return <code>true</code> if the given object represents
 * an <code>Email</code> with the same address, <code>false</code> otherwise.
 */
@Override
public boolean equals(Object other) {
 

For the hashCode() method:

/**
 * Returns the hash code for this <code>Email</code> object.
 * The returned hash code will be the hash code of the email address string		
 * @return a hash code value for this object.
 */
@Override
public int hashCode() {
 

For the compareTo() method:

/**
 * Compares this <code>Email</code> to the argument,
 * alphabetically by the email address string.
 * @param otherEmail the <code>Email</code> to compare against.
 * @return the value zero if the email address strings are the same,
 * a value less than zero if this email is alphabetically
 * before the argument, and a value greater than zero if this email
 * is alphabetically after the argument.
 */
@Override
public int compareTo(Email otherEmail) {
 

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:

/**
 * Validate that the email:
 * 1. Has no spaces;
 * 2. Has exactly one @ character;
 * 3. Local-part is not empty;
 * 4. Domain-part contains at least one dot;
 * 5. Domain-part sections are not empty.
 * @throws <code>IllegalArgumentException</code> if the argument is not a valid email.
 * @throws <code>NullPointerException</code> if the argument is <code>null</code>
 */
private void validate() {
 

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:

<!--
To change this template, choose Tools | Templates
and open the template in the editor.
-->
<!DOCTYPE html>
<html>
    <head>
        <title></title>
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    </head>
    <body>
        <div>The <code>com.example.util</code> package contains	general utility classes.</div>
    </body>
</html>
 

Regenerate the Javadoc to see the package description appear on the initial page.

More detail about Javadoc can be found at the following link:

How to write Javadoc comments

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.

Next lesson: 10.2 How to test a class using JUnit