mirrors
/
org.aspectj
mirror of https://github.com/eclipse/org.aspectj.git


			
				
					
						
						
							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>
    &lt;ajc-test 
        dir="common" 
        title="language-initialization constructor-call example">
        ...
    &lt;/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>
    &lt;compile files="declares/Declares.java, {others}"
        &lt;message kind="error" line="15" text="Factory"/>
    &lt;/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>