123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228 |
- <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.
- Finally, the <a href="testsrc">testsrc/</a> directory is reserved for
- code used to test the other code in the sandbox. There should
- be no samples under testsrc.
-
- <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>
-
- If the code is broken (e.g., if it no longer works in the latest
- version of AspectJ), then prefix SAMPLE with BROKEN in the tag:
-
- <pre>
- {comment} START-<skipParse/>BROKEN-SAMPLE ...
- ... sample code ...
- {comment} END-<skipParse/>BROKEN-SAMPLE ...
- ... more text ...
- </pre>
-
- It will no longer be gathered, but can be fixed and reinstated.
-
- <p>
- Happy coding!
- <hr>
-
- </body>
- </html>
|