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
156
157
158
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: -->
|
