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
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
<html>
<title>README - AspectJ sandbox for sample code and instructions</title>
<body>
<h2>README - AspectJ sandbox for sample code and instructions</h2>
This directory is a place to put scraps that might end up in the
AspectJ documentation or on the web site:
<ul>
<li>sample code for AspectJ programs,
</li>
<li>sample code for extensions to AspectJ tools and API's,
</li>
<li>sample scripts for invoking AspectJ tools, and
</li>
<li>documentation trails showing how to do given tasks
using AspectJ, AJDT, or various IDE or deployment
environments.
</li>
</ul>
In the past, we found it tedious to keep and verify
sample code used in documentation because it involves
copying the code from the documentation
into a form that can be tested (or vice versa).
Further, there are a lot of tips and sample code
contributed on the mailing lists, but they can be
difficult to find when needed. This aims to be
a place where such contributions can be gathered,
kept in good order, and extracted for use in docs,
without too much overhead.
<p>
Code in the sandbox is kept in a running state;
it's tested by running the harness on the sandbox
test suite file
<a href="sandbox-test.xml">sandbox-test.xml</a>
or
<a href="sandbox-api-test.xml">sandbox-api-test.xml</a>.
To extract the code for documentation, we use a tool
that recognizes
a sample within a source file if it has comments
signalling the start and end of the sample.
Keeping sample code in sync with the documentation
and with the test suite specification only takes
a bit of care with formatting and comments.
The rest of this document tells how.
<h3>Documenting samples</h3>
<p><code>org.aspectj.internal.tools.build.SampleGatherer</code>
(in the build module) extracts samples
of the following form from any "source" file
(currently source, html, text, and shell scripts):
<pre>
... some text, possibly including @author tags
{comment} START-<skipParse/>SAMPLE [anchorName] [anchor title] {end-comment}
... sample code ...
{comment} END-<skipParse/>SAMPLE [anchorName] {end-comment}
... more text ...
</pre>
<p>
Each sample extracted consists of the code and associated
attributes: the source location, the anchor name
and title, any text flagged with XXX,
and the author pulled from the closest-preceding
<code>@author</code> tag. (If there is no author,
the AspectJ team is presumed.)
<code>SampleGatherer</code> can render the collected
samples back out to HTML (todo: or DocBook) for
inclusion in the FAQ, the online
samples, the Programming Guide, etc.
An editor might reorder or annotate the samples
but the code should not be edited
to avoid introducing mistakes.
<p>To help keep the sample code in sync with the docs...
<ul>
<li>Use comments in the sample to explain the code,
rather than describing it in the documentation.
</li>
<li>Preformat samples to be included without modification
in docs:
<ul>
<li>Use 4 spaces rather than a tab for each indent.
</li>
<li>Keep lines short - 60 characters or less.
</li>
<li>In Java, code taken out of context of the defining type
can be indented only once in the source code,
even though they might normally be indented more.
</li>
<li>In AspectJ, indent advice pointcuts beyond the block code:
<pre>
before() : call(!public * com.company.library..*.*(String,..))
&& within(Runnable+) { // indent once more than code
// code here
}
</pre>
</li>
</ul>
</li>
</ul>
<p>
Where you put the sample code depends on how big it is
and what it's for. Any code intended as an extension to
the AspectJ tools goes in the <a href="api-clients">api-clients/</a>
directory.
Most code will instead be samples of AspectJ programs.
Subdirectories of this directory should be the base directories of
different source sets.
The <a href="common">common/</a> directory should work for
most code snippets, but standalone, self-consistent code
belongs in its own directory,
as do sets pertaining to particular publications or tutorials.
An example of this are the sources for the "Test Inoculated"
article in the <a href="inoculated">inoculated/</a> directory.
<h3>Testing samples</h3>
We try to make sure that the samples we present to people
actually work by testing each kind differently:
<ul>
<li>Most Java and AspectJ programs are tested using
<a href="sandbox-test.xml">sandbox-test.xml</a>.
</li>
<li>API clients are tested using
<a href="sandbox-api-test.xml">sandbox-api-test.xml</a>,
which requires building <code>aspectjtools.jar</code>.
</li>
<li>Shell and Ant scripts should be run per instructions.
</li>
<li>HTML and text files must be manually reviewed.
</li>
</ul>
When adding Java or AspectJ code, add a corresponding test case
in <a href="sandbox-test.xml">sandbox-test.xml</a>.
This file has the same format as other harness test suites;
for more information,
see <a href="../../tests/readme-writing-compiler-tests.html">
../../tests/readme-writing-compiler-tests.html</a>.
The test suite should run and pass after new code is added
and before samples are extracted.
<p>To keep Java/AspectJ code in sync with the tests:
<ul>
<li>The test title should be prefixed with the anchor name and
have any suffixes necessary for clarity and to make sure
there are unique titles for each test.
E.g., for a sample with the anchor
"<code>language-initialization</code>",
<pre>
<ajc-test
dir="common"
title="language-initialization constructor-call example">
...
</ajc-test>
</pre>
(Someday we'll be able to compare the test titles with
the anchor names to verify that the titles contain
all the anchor names.)
<p></li>
<li>Avoid mixing compiler-error tests with ordinary code,
so others can reuse the target code in their samples.
Most of the sample code should compile.
<p></li>
<li>Any code that is supposed to trigger a compiler error
should be tested by verifying that the error message
is produced, checking either or both of the line number
and the message text. E.g.,
<pre>
<compile files="declares/Declares.java, {others}"
<message kind="error" line="15" text="Factory"/>
</compile>
</pre>
Where a test case refers to a line number,
we have to keep the expected message
and the target code in sync.
You can help with this by adding a comment in the target code
so people editing the code know not to fix
or move the code. E.g.,
<pre>
void spawn() {
new Thread(this, toString()).start(); // KEEP CE 15 declares-factory
}
</pre>
Any good comment could work, but here are some optional conventions:
<p>
<ul>
<li>Use "CE" or "CW" for compiler error or warning, respectively.
<p></li>
<li>Specify the line number, if one is expected.
<p></li>
<li>Specify the affected test title(s) or sample code anchor label
to make it easier to find the test that will break if the
code is modified. (The editor can also run the tests
to find any broken ones.)
<p>
</li>
</ul>
</li>
</ul>
<p>
Happy coding!
<hr>
</body>
</html>
|
