JavaDoc Notes
September 2008


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

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()


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.


@see

This is useful. You can put text after it or do something like:

@see com.acme.fun.FunManager.doIt( String )

This will result in a clickable link to the Javadoc for the doIt() method (assuming it's in the same Javadoc somewhere.