diff options
Diffstat (limited to 'docs/sandbox/readme-sandbox.html')
| -rw-r--r-- | docs/sandbox/readme-sandbox.html | 192 |
1 files changed, 192 insertions, 0 deletions
diff --git a/docs/sandbox/readme-sandbox.html b/docs/sandbox/readme-sandbox.html new file mode 100644 index 000000000..d8c874399 --- /dev/null +++ b/docs/sandbox/readme-sandbox.html @@ -0,0 +1,192 @@ +<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 some 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>. +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. + +<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>Code snippets 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>Indent advice pointcuts once 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. + +<p> +When adding 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 sample 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> + |