diff options
Diffstat (limited to 'docs/sandbox/readme-sandbox.html')
| -rw-r--r-- | docs/sandbox/readme-sandbox.html | 228 |
1 files changed, 0 insertions, 228 deletions
diff --git a/docs/sandbox/readme-sandbox.html b/docs/sandbox/readme-sandbox.html deleted file mode 100644 index e83539882..000000000 --- a/docs/sandbox/readme-sandbox.html +++ /dev/null @@ -1,228 +0,0 @@ -<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> - |