1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
<refentry>
<refnamediv>
<refname>ajdoc</refname>
<refpurpose>generate HTML API documentation, including crosscutting structure (early-access)
</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>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
Similar to <command>javadoc</command>,
<command>ajdoc</command> renders HTML documentation for pointcuts,
advice, and inter-type declarations, as
well as the Java constructs that Javadoc renders.
<command>ajdoc</command> also links
advice from members affected by the advice and
the inter-type declaration for members declared from aspects.
The aspect will be fully documented,
as will your target classes, including links to any
advice or declarations that affect the class.
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> 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> 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: -->
|
