Aspectj Cookbook

2017-07-07 02:10:07

Recipe 2.6. Generating Javadoc Documentation

Problem

You want to generate javadoc format documentation for your AspectJ application.

Solution

Use the ajdoc tool from the command line or from within Eclipse.

Discussion

Java developers have used the javadoc tool for generating comprehensive documentation for their Java applications since Java 1.1. The javadoc tool was never designed to handle the new language constructs that AspectJ introduces and is not able to generate documentation for an AspectJ application. To meet this problem, the developers of AspectJ created ajdoc, a tool that extends javadoc so that it can correctly and usefully document the aspect-oriented structures in your application.

Providing your environment has been set up correctly, as shown in Recipe 2.1, the ajdoc tool can be accessed from the command line by typing the following command:

> ajdoc -sourcepath <The root location of you code> -d <The directory in which you want your documentation to be placed> <The file locations of each of the classes aspects and classes to include in the generated documentation>

The ajdoc tool provides the -argfile parameter so that you can provide an explicit AspectJ build configuration .lst file, as mentioned in Recipe 2.3. A .lst file contains the build configuration for a set of classes and aspects in your application for which documentation should be produced.

Using ajdoc means that you can now document your pointcuts, advice, and aspects as shown in Example 2-5.

Example 2-5. Applying javadoc tags to the aspects, pointcuts, and advice

package com.oreilly.aspectjcookbook; /** * A simple aspect to weave in a HelloWorld message when foo(int,name) * is called on objects of the MyClass class. * @author russellmiles * @version 1.0 * */ public aspect HelloWorld { /** * Selects join points on calls to the MyClass.foo(int,String) method. */ pointcut callPointCut( ) : call(void com.oreilly.aspectjcookbook.MyClass.foo(int, String)); /** * Simple before advice that prints HelloWorld to the standard output. */ before( ) : callPointCut( ) { System.out.println( "Hello World"); System.out.println( "In the advice attached to the call point cut"); } }

Example 2-5 is the same aspect that was shown in Recipe 2.2 but highlights the documentation that is provided for the ajdoc tool. To produce documentation from the command line for this simple example, you would type the following from the same directory as your source code, making sure that your AspectJ build environment has been set up correctly (also shown in Recipe 2.2) and that the docs directory has been created ready to accept your generated documentation:

> ajdoc -sourcepath . -d docs com/oreilly/aspectjcookbook/MyClass.java com/ oreilly/ aspectjcookbook/HelloWorld.java

If the ajdoc tool runs correctly, you should see something like the following lengthy but successful output from the previous command:

> Calling ajc... > Building signature files... > Calling javadoc... Loading source file /source/Chapter 2/2.5/ajdocworkingdir/com/oreilly/ aspectjcookbook/MyClass.java... Loading source file /source/Chapter 2/2.5/ajdocworkingdir/com/oreilly/ aspectjcookbook/HelloWorld.java... Constructing Javadoc information... Standard Doclet version 1.4.2_03 Generating constant-values.html... Building tree for all the packages and classes... Building index for all the packages and classes... Generating overview-tree.html... Generating index-all.html... Generating deprecated-list.html... Building index for all classes... Generating allclasses-frame.html... Generating allclasses-noframe.html... Generating index.html... Generating packages.html... Generating com/oreilly/aspectjcookbook/package-frame.html... Generating com/oreilly/aspectjcookbook/package-summary.html... Generating com/oreilly/aspectjcookbook/package-tree.html... Generating com/oreilly/aspectjcookbook/HelloWorld.html... Generating com/oreilly/aspectjcookbook/MyClass.html... Generating package-list... Generating help-doc.html... Generating stylesheet.css... > Decorating html files... > Decorating /source/Chapter 2/2.5/com/oreilly/aspectjcookbook/ MyClass.html... > Decorating /source/Chapter 2/2.5/com/oreilly/aspectjcookbook/ HelloWorld.html... > Removing generated tags (this may take a while)... > Finished.

The ajdoc tool is also available from within the Eclipse IDE when using the AspectJ Development Tools (AJDT) plug-in. To use the ajdoc tool, select your AspectJ project in the Package Explorer panel and click Project Generate Javadoc....

When Eclipse shows the Generate Javadoc dialog, you will need to change the Javadoc Command to ajdoc. To do this, click on the Configure button and then navigate to the place where the ajdoc tool has been installed; normally, this is %HOME DIRECTORY%/aspectj1.2/bin. Select the ajdoc tool and click on OK. The Javadoc Command should then change to point to the ajdoc tool to indicate that it has been configured as the tool to use when generating your projects documentation. Because the ajdoc tool works in almost the same way as the javadoc tool, Eclipse needs to know nothing more to use the new configuration and you can set up the options for your javadoc generation as normal.

As of Eclipse 3 and AJDT 1.1.11, the process for generating documentation using ajdoc has been simplified. Before, you had to manually set the javadoc generation to the ajdoc tool; with the release of these versions, the ajdoc documentation has its own menu item that can be accessed by clicking on Project Generate ajdoc....