Javadoc Notes

Russell Bateman
September 2008

Javadoc was originally cased, "JavaDoc," but that spelling has fallen out of favor most everywhere. See Wikipedia article.


Order of block tags...

Include block tags in the following order:

  @param (classes, interfaces, methods and constructors only)
  @return (methods only)
  @exception (@throws is a synonym added in Javadoc 1.2)
  @author (classes and interfaces only, required)
  @version (classes and interfaces only, required. See footnote 1)
  @see
  @since
  @serial (or @serialField or @serialData)
  @deprecated (see How and When To Deprecate APIs)

@param

The @param tag is followed by the name (not data type) of the parameter, followed by a description of the parameter. By convention, the first noun in the description is the data type of the parameter. (Articles like "a", "an", and "the" can precede the noun.) An exception is made for the primitive int, where the data type is usually omitted. Additional spaces can be inserted between the name and description so that the descriptions line up in a block. Dashes or other punctuation should not be inserted before the description, as the Javadoc tool inserts one dash.

Parameter names are lowercase by convention. The data type starts with a lowercase letter to indicate an object rather than a class. The description begins with a lowercase letter if it is a phrase (contains no verb), or an uppercase letter if it is a sentence. End the phrase with a period only if another phrase or sentence follows it.


Default @author for Javadoc

This comes out as the name of the (Linux) user. To change this, create a Launcher shortcut and type the Launcher->Command as 

	/home/russ/dev/eclipse/europa/eclipse -vmargs -Duser.name="Russell Bateman"

Note: “user.name” is a Java property.


Forwarding Javadoc with @see or {@link ...}

To reuse an existing Javadoc blurb, create the method comment thus: 

  .
  .
  .
  /* (non-Javadoc)
   * @see package-path.class#method-name()
   */
  public void method()
  {
  .
  .
  .

For example, ... 

public class AcmeClass implements Runnable
{
  /* (non-Javadoc)
   * @see java.lang.Runnable#run()
   */
  public void run()
  {
    try
    {
      Thread.sleep( 5000 );
    }
    catch( InterruptedException e )
    {
      e.printStackTrace();
    }

    System.out.println( "AcmeClass.run() exiting" );
  }
}

What shows up when the Java doc for this run method is got is the doc for the Run() of java.lang.Runnable:

When an object implementing interface Runnable is used to create a thread, starting the thread causes the object's run method to be called in that separately executing thread.

The general contract of the method run is that it may take any action whatsoever.

See Also:
            java.lang.Thread.run()

Also, here's how to link to constructors in another class. 

public class Pv1 extends SegmentPojo  // and there is a "primary" subclass, Pid
{
  /** See {@link Pid#Pid( Segment )}. */
  public Pv1( Segment segment ) { this.segment = segment; }

  /** See {@link Pid#Pid( String )}. */
  public Pv1( final String segmentString ) throws HL7Exception
  {
    segment = getSegment( getParser().parse( MESSAGE + segmentString ), "PV1" );
  }

Linking to Javadoc in Eclipse

Read my article, JARs and Eclipse Build Path, to learn about using ant to generate Javadoc. However, don't ever incorporate Javadoc into an Eclipse project. Javadoc generates very stinky HTML which will cause Eclipse to issue countless warnings. Keep your Javadoc remote to the project.


Generating Javadoc in Maven

Add these lines describing the Maven Javadoc plug-in in pom.xml:

This will generate the Javadoc and copy it to subdirectory documents off your project root: 

<build>
  <plugins>
    .
    .
    .
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>3.2.0</version>
      <configuration>
        <quiet>true</quiet>
        <skip>false</skip>
        <doclint>none</doclint>
        <noqualifier>all</noqualifier>
        <reportOutputDirectory>${user.dir}/documents</reportOutputDirectory>
        <destDir>javadoc</destDir>
      </configuration>
      <executions>
        <execution>
          <id>attach-javadocs</id>
          <phase>package</phase>
          <goals>
            <goal>jar</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
    .
    .
    .
  </plugins>
</build>

...then execute Maven: 

$ mvn package

If a multimodule project, however, the top-level pom.xml file gets the following (and there is nothing to do in the subordinate pom.xml files): 

<build>
  <plugins>
    .
    .
    .
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>3.2.0</version>
      <configuration>
        <noqualifier>all</noqualifier>
        <destDir>javadoc</destDir>
      </configuration>
      <executions>
        <execution>
          <id>aggregate</id>
          <goals>
            <goal>aggregate;/goal>
          </goals>
          <configuration>
            <reportOutputDirectory>${user.dir}</reportOutputDirectory>
            <destDir>javadoc</destDir>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Don't put reportOutputDirectory into the plug-in configuration, but into the plug-in execution configuration as it will overwrite what was generated by the previous submodule. The solution is to use the default output directory and configure the output directory for the aggregated Javadoc instead. The Maven reactor build wil create Javadoc output files in each module's target subdirectory which are then combined into the root project's target subdirectory on the path ./target/site/apidocs/javadoc/index.html (c'est-à-dire, that's what you should launch in your browser to view all of your Javadoc).

However, I found that, in order to build without error and get the aggregation to work, I had to use the install goal in the following command—. install is not a Maven goal I happen to use much in my project lifecycles: 

$ mvn install javadoc:javadoc javadoc:aggregate

I'm a little uneasy about this answer because I don't understand much of what's happening, but that plagues much of my familiarity (or lack thereof) with Maven anyway. And, I find that I can't get it to work as part of the Maven build.

If you would rather go with a command-line approach (in bash), here is how I once did it and it worked very well: 

$ alias do-javadoc='mvn clean install javadoc:javadoc javadoc:aggregate'

I keep a tab up in Chrome: 

file:///home/russ/sandboxes/project/target/site/apidocs/javadoc/index.html

that I can refresh such that I always have the latest Javadoc on the whole project. Doing this makes me a) more sensitive to the Javadoc I'm writing and how useful or useless it is, and b) realize how much time I can save using it instead of killing open editor windows to look for information that I have already written for use in a handy and elegant format (i.e.: HTML/CSS).

As I say, why isn't this happening automatically when I build? First, because, despite lots of research and forum diving in stackoverflow and elsewhere, no one has adequately documented how to do generate Javadoc as part of the Maven build. Second, it takes much longer than a simple build (from my observation) and I wouldn't want to have to add that thumb-twiddling to the time I already must endure when I type mvn clean package. As it is, this working at all does require some intervention in the root pom.xml that I can show you if you need.


Errors, errors and more errors...

This builds on what was said at the end of the previous note...

All of this Javadoc plug-in was put together by a sailor on an alcohol-fueled weekend binge. There is little reason to being able to make this work. You just randomly try suggestions you google each time Javadoc generation ceases to work for whatever reason until it works, which it will not for very long.

Here are some points I retain. I got this all working 6 months ago only to discover it has stopped. I got it going again today.

That tab open in Chrome I used to keep seems to have become less useful. I think the Javadoc generation has changed with the Java I'm now using. This seems a better URL now: 

file:///home/russ/sandboxes/etl/code/acme-pipeline/target/site/apidocs/javadoc/allclasses-index.html