org.aspectj/docs/devGuideDB/ajdoc.xml

<refentry id="ajdoc-ref" xreflabel="The ajdoc Command-line Reference">  
<refnamediv>
    <refname>ajdoc</refname>
    <refpurpose>generate HTML API documentation, including crosscutting structure
    </refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>ajdoc</command>
      <arg choice="opt">
        -bootclasspath <replaceable>classpathlist</replaceable>
      </arg>
      <arg choice="opt">
        -classpath <replaceable>classpathlist</replaceable>
      </arg>
      <arg choice="opt">-d <replaceable>path</replaceable></arg>
      <arg choice="opt">-help</arg>
      <arg choice="opt">-package</arg>
      <arg choice="opt">-protected</arg>
      <arg choice="opt">-private</arg>
      <arg choice="opt">-public</arg>
      <arg choice="opt">-overview <replaceable>overviewFile</replaceable></arg>
      <arg choice="opt">
        -sourcepath <replaceable>sourcepathlist</replaceable>
      </arg>
      <arg>-verbose</arg>
      <arg>-version</arg>
      <group>
        <arg><replaceable>sourcefiles...</replaceable></arg>
        <arg><replaceable>packages...</replaceable></arg>
        <arg>@<replaceable>file...</replaceable></arg>
        <arg>-argfile <replaceable>file...</replaceable></arg>
      </group>
      <arg choice="opt">
        <replaceable>ajc options</replaceable>
      </arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>
      <command>ajdoc</command> renders HTML documentation for AspectJ 
      constructs as well as the Java constructs that 
      <command>javadoc</command> renders.
      In addition <command>ajdoc</command> displays the crosscutting
      nature in the form of links. That means, for example, that 
      you can see everything affecting a method when reading 
      the documentation for the method.
    </para>

    <para>
      To run <command>ajdoc</command>, use one of the scripts in the 
      AspectJ <filename>bin</filename> directory. 
      The <command>ajdoc</command> implementation builds on Sun's <command>javadoc</command> 
      command line tool, and you use it in the same way with many of
      the same options
      (<command>javadoc</command> options are not documented here;
      for more information on <command>javadoc</command> usage, see the
      <ulink url="http://java.sun.com/j2se/javadoc/">Javadoc homepage</ulink>.)
    </para>

    <para>
      As with <command>ajc</command> (but unlike <command>javadoc</command>),
      you pass <command>ajdoc</command> all your aspect source files 
      and any files containing types affected by the aspects;
      it's often easiest to just pass all the <filename>.java</filename> 
      and <filename>.aj</filename> files in your system.
      Unlike <command>ajc</command>,
      <command>ajdoc</command> will try to find package sources using the
      specified sourcepath if you list packages on the command line. 
    </para>


    <para>
      To provide an argfile listing the source files, you can use
      use the same argfile (<filename>@filename</filename>) conventions 
      as with <command>ajc</command>.  
      For example, the following documents all the source files listed
      in <filename>argfile.lst</filename>, sending the output to
      the <literal>docDir</literal> output directory.

      <programlisting>ajdoc -d docDir @argfile.lst</programlisting>

      See the <link linkend="ajc">ajc documentation</link> 
      for details on the text file format.
    </para>

	<para>
	  <command>ajdoc</command> honours <command>ajc</command> options. See
      the <link linkend="ajc_options">ajc documentation</link> for details on
      these options.
	</para>

    <para>
      <command>ajdoc</command> currently requires the 
      <filename>tools.jar</filename> from J2SE 1.3 to be on the classpath.
      Normally the scripts set this up, assuming that your <literal>JAVA_HOME</literal>
      variable points to an appropriate installation of Java.
      You may need to provide this jar when using a different
      version of Java or a JRE.
    </para>

  </refsect1>

  <refsect1>
    <title>Examples</title>
    <example id="ajdocdocumentingspacewar"> <!-- docbook bug - rendering this as example 4? -->
      <title>Documenting Spacewar</title>
      <itemizedlist>
  	    <listitem>
  	      <para>
  	        Change into the <filename>examples</filename> directory.
  	      </para>
  	    </listitem>

  	    <listitem>
  	      <para>
  	        Type <userinput>mkdir doc</userinput> to create the
  	        destination directory for the documentation.
  	      </para>
  	    </listitem>
 	    <listitem>
	        <para>
	          Type <userinput>ajdoc -private -d doc spacewar
	            coordination</userinput> to generate the documentation.
	        </para>
	        <itemizedlist>
	          <listitem>
	            <para>
		      (Use <literal>-private</literal> to get all members, since
            may of the interesting ones in spacewar are not public.)
	            </para>
	          </listitem>
	        </itemizedlist>
	      </listitem>
	      <listitem>
	            <para>
              Type <userinput>ajdoc -private -d doc @spacewar/demo.lst</userinput> 
              to use the argfile associated with Spacewar.  
  	            </para>
  	      </listitem>
  	      <listitem>
  	        <para>
  	          To view the documentation, open the file <filename>index.html</filename> 
              in the <filename>doc</filename> directory using a web browser.
  	        </para>
  	      </listitem>
        </itemizedlist>
      </example>
  </refsect1>
</refentry>

<!-- Local variables: -->
<!-- fill-column: 79 -->
<!-- sgml-local-ecat-files: devguide.ced -->
<!-- sgml-parent-document:("devguide.sgml" "book" "refentry") -->
<!-- End: -->