AspectXdoc

This page gives an overview of the AspectXdoc facility. AspectXdoc is a JavaDoc-like program for the automatic generation of HTML documentation for aspect programs written in AspectX. AspectXdoc is implemented as a set of XSL programs that read the XML documents containing the AspectX programs, extract the comments from them and use them to construct a web site that documents the programs.

The format of the HTML documentation generated by AspectXdoc is similar to the format of the documentation generated by the doxygen tool. For an example, readers can refer to the documentation of the sample programs provided with this web site.

Usage

The XSD that defines the AspectX language allows "description" elements to be placed inside the following elements:

  • aspect
  • pointcut
  • advice

These elements are intended to document the aspect program. Note that description elements can contain any HTML tags. AspectXdoc processes the description elements and their content.

The documentation web site gathers together the aspect programs in groups where each group brings together a set of logically related aspect programs. The master program implementing the AspectXdoc facility is the AspectXdoc.xsl program. This program reads its input from the AspectXdoc configuration file. This is an XML-based document that defines the following items:

  • The title of the documentation web site
  • An introduction to the documentation web site
  • The directory where the documentation web site will be constructed
  • The list of files holding the aspect programs
  • The groups to which the aspect programs are assigned (see below)
  • The text to be entered as HTML header in the documentation web site
  • The text to be displayed at the bottom of each page of the documentation web site

A more detailed description of how the configuration file is structured can be found in the comments of the configuration file provided for the sample programs (AspectXLib/AspectXdocConfig.xml).

The AspectXdoc program is best run from an ant build file. An example of an ant build file that contains a target to run the AspectXdoc application can be found here: AspectXLib/build.xml.