For our experiments, we are going to use the VehicleUtils.groovy class, which should be placed under the src/org/groovy/cookbook directory inside your current folder. The class contains several Javadoc-like comments in order to demonstrate Groovydoc's capabilities:

package org.groovy.cookbook

/**
 * This class contains vehicle related
 * calculation utility methods.
 *
 * @author Groovy Writer
 * @since 2013
 *
 */
class VehicleUtils {

    /**
     * Returns average fuel consumption per 100 km.
     * More information about involved calculations
     * can be found in the
     * <a
     *  
     * >respected source</a>.
     *
     * @param distance
     *           the distance driven by the vehicle.
     * @param liters
     *           the amount of fuel spent in liters.
     *
     * @return calculated fuel consumption.
     *
     */
    static fuelConsumptionPer100Km(distance, liters) {
      (liters * 100) / distance
    }
}

As you can see, there is not much difference in the formatting of comments compared to javadoc.

If we try to use the javadoc command (executed from your current directory) to generate documentation for that class, it will not find any source files:

> javadoc -sourcepath src org.groovy.cookbook
Loading source files for package org.groovy.cookbook...
javadoc: warning -
   No source files for package org.groovy.cookbook
Constructing Javadoc information...
javadoc: warning -
   No source files for package org.groovy.cookbook
javadoc: error -
   No public or protected classes found to document.
1 error
2 warnings

Even if you rename VehicleUtils.groovy to VehicleUtils.java, javadoc will still complain about unrecognized syntax (since javadoc is re-using javac functionality):

./src/org/groovy/cookbook/VehicleUtils.java:1:
   ';' expected
package org.groovy.cookbook
                           ^
./src/org/groovy/cookbook/VehicleUtils.java:25:
    <identifier> expected
  static def fuelConsumptionPer100Km(distance, liters) {
                                             ^
...

5 errors

This all leads to the necessity of using Groovydoc for generating documentation. Groovydoc is installed together with Groovy, and if you followed one of the installation recipes (see the Installing Groovy on Linux and OS X or the Installing Groovy on Windows recipes in Chapter 1, Getting Started with Groovy) correctly, the groovydoc command should already be available in your shell.

By simply typing the groovydoc command, you'll get default help message with parameter description.

Under the hood, groovydoc acts similar to javadoc by parsing the source files and navigating internally to the AST (Abstract Syntax Tree) to extract comment information and convert it to a set of HTML files.

Groovydoc supports all the standard Javadoc tags such as @author, @see, @since, @param, @return, and some others.

Groovydoc can also be used to generate documentation for Java source code since by design, Groovy fully supports Java syntax. This is very handy since, in the case of a combined code base, which contains both Java and Groovy source code files, you can take advantage of using the same tool to produce joint documentation.

For example, we can add the Vehicle.java source file inside the src/org/groovy/cookbook folder:

package org.groovy.cookbook;

/**
 * This class contains vehicle data structure.
 *
 * @author Groovy Writer
 * @since 2013
 *
 */
public class Vehicle {

  final double maxSpeed;

  public Vehicle(double maxSpeed) {
    this.maxSpeed = maxSpeed;
  }

  /**
   * Returns vehicle's maximum speed.
   */
  public double getMaxSpeed() {
    return maxSpeed;
  }

}

If we run the groovydoc tool again, it will happily create documentation for both classes:

Groovydoc is also well integrated with the build tools described in the Integrating Groovy into the build process using Ant and Integrating Groovy into the build process using Gradle recipes.