diff options
Diffstat (limited to 'docs/devguide/ajdoc.xml')
| -rw-r--r-- | docs/devguide/ajdoc.xml | 159 |
1 files changed, 159 insertions, 0 deletions
diff --git a/docs/devguide/ajdoc.xml b/docs/devguide/ajdoc.xml new file mode 100644 index 000000000..d2a763d59 --- /dev/null +++ b/docs/devguide/ajdoc.xml @@ -0,0 +1,159 @@ +<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: --> |