to pdguide added XLint list, more control options, debugging pointcuts, and more hand-holding.

6 files changed, 484 insertions, 121 deletions

diff --git a/docs/pdGuideDB/ajcore.xml b/docs/pdGuideDB/ajcore.xml
index f1cf17681..838c6d7b4 100644
--- a/docs/pdGuideDB/ajcore.xml
+++ b/docs/pdGuideDB/ajcore.xml
@@ -1,4 +1,4 @@
-<chapter id="ajcore" xreflabel="AspectJ Core">
+<chapter id="ajcore" xreflabel="AspectJ Core Files">
     <title>AspectJ Core Files</title>
     
     <sect1 id="ajcore-introduction">
@@ -10,12 +10,11 @@
         the date and time that the file was produced 
         e.g. <literal>ajcore.20060810.173655.626.txt</literal>. The file contains details
         of the problem such as the exception thrown as well as information about the
-        environement such as operating system and Java version. </para>
-        
-        <para> </para>
-    
+        environment such as operating system and Java version. When submitting a bug,
+        include this file whenever it is available.</para>
+            
         <sect2 id="configuration" xreflabel="configuration">
-            <title>Configuration</title>
+            <title>Configuring dump files</title>
             
             <para> By default AspectJ will only create an <literal>ajcore</literal> file 
             when an unexpected exception is thrown by the weaver or an 
@@ -61,8 +60,8 @@
             </informaltable>
   		</sect2>
 
-        <sect2 id="examples" xreflabel="examples">
-            <title>Examples</title>
+        <sect2 id="ajcore-examples" xreflabel="AJCore File Examples">
+            <title>AJCore File Examples</title>
         
             <para> Below is an extract from an <literal>ajcore</literal> file. You will see
             details of the dump configuration as well as the exception (with stack trace) that
diff --git a/docs/pdGuideDB/ltwdump.xml b/docs/pdGuideDB/ltwdump.xml
index 36b1bea3a..049f2e4f5 100644
--- a/docs/pdGuideDB/ltwdump.xml
+++ b/docs/pdGuideDB/ltwdump.xml
@@ -1,38 +1,35 @@
-<chapter id="ltwdump" xreflabel="LTW Dump">
-    <title>LTW Dump</title>
+<chapter id="ltwdump" xreflabel="Dumping classes during load-time weaving">
+    <title>Dumping classes during load-time weaving</title>
     
     <sect1 id="ltwdump-introduction">
         <title>Introduction</title>
         
-        <para> Occasionally problems may be encountered with classes that have been load-time woven. 
-        Symptoms will include incorrect program function or a Java exception such as 
-        <literal>java.lang.VerifyError</literal>. Problems can be caused by the way 
-        an aspect or class is built, incompatibilities between AspectJ and 
-        generated byte-code 
-        e.g. <ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=117854">CGLIB</ulink>
-        or a bug in the weaver.
-        When these problems occur it may be necessary to attach the class files concerned
-        to a bug report. AspectJ can be configured to dump byte-code to disk using
-        <literal>META-INF/aop.xml</literal>. The <literal>_ajdump</literal> subdirectory the the current
-        working directory is used. </para>
-    
-        <sect2 id="configuration" xreflabel="configuration">
-            <title>Configuration</title>
-            
-            <para> See the 
+        <para> 
+            Very rarely, problems present not at build-time but at run-time,
+            with <literal>java.lang.VerifyError</literal> or incorrect behavior.
+            In these situations, it's most helpful to include the offending class 
+            in the bug report.  But with load-time weaving, the woven classes are 
+            in memory only; to save classes woven at load-time, configure
+            <literal>META-INF/aop.xml</literal> to dump the classes (by default 
+            to an <literal>_ajdump</literal> subdirectory of the current working 
+            directory).  Also, if the input class file is not available (e.g., if
+            the AspectJ weaver is after another bytecode weaver), you can
+            also configure the weaver to dump the input classes.
+        </para>
+        <sect2 id="ltw-examples" xreflabel="ltwdump-configuration">
+            <title>Configuring bytecode dumping in load-time weaving</title>
+            <para>
+  			For details of how to configure byte-code dumping, see the             
+            AspectJ Development Environment Guide section on 
 				<ulink url="../devguide/ltw-configuration.html#configuring-load-time-weaving-with-aopxml-files">
-				Development Environment Guide</ulink>
-  				for details of how to configure byte-code dumping. </para>
-  		</sect2>
+				Configuring Load-time Weaving</ulink>.  
+            Following is a simple example.
+            </para>
+            </sect2>
 
-        <sect2 id="examples" xreflabel="examples">
-            <title>Examples</title>
-        
-            <para> By default AspectJ will dump byte-code only after it is woven. This 
-            is because usually the original class file is already available. However 
-            byte-code is sometimes generated by frameworks or downloaded over the network
-            in which case AsepctJ can dump the byte-code before it is woven too. </para>
-            
+        <sect2 id="ltwdump-examples" xreflabel="LTW Dump Examples">
+            <title>LTW Dump Examples</title>
+                    
             <para> The following <literal>META-INF/aop.xml</literal> will 
             weave classes in the <literal>com.foo</literal> package (and subpackages) but not
             CGLIB generated classes in the <literal>com.foo.bar</literal> package (and subpackages). 
diff --git a/docs/pdGuideDB/messages.xml b/docs/pdGuideDB/messages.xml
index 44b1189bd..cadb2a0df 100644
--- a/docs/pdGuideDB/messages.xml
+++ b/docs/pdGuideDB/messages.xml
@@ -3,49 +3,53 @@
     
     <sect1 id="messages-introduction">
         <title>Introduction</title>
-        
-        <para> By default only warning and error messages are issued by the compiler whether it is
-        being used for source code compilation, weaving, binary weaving or load-time weaving. Informational,
-        debug and weaving messages can also be obtained using compiler options 
-        or System properties. Also as well as being able to soften or ignore 
-        certain error messages the various <literal>-Xlint</literal> 
-        <ulink url="../devguide/ajc-ref.html">options</ulink> can be used to 
-        notify you of conditions that would otherwise be ignored. </para>
-
-		<para> It is often difficult to determine, especially when using load-time weaving (LTW),
-		why advice has not been woven. Here is a quick guide to the messages to
-		look for. Firstly if you use the <literal>-verbose</literal> option you 
-		should see the following message when your aspect is registered: </para>
-
-        <programlisting><![CDATA[
-	info register aspect MyAspect
-        ]]></programlisting>
-
-		<para> Secondly if you use the <literal>-debug</literal> option you should 
-		see a message indicating that you class is being woven: </para>
-
-        <programlisting><![CDATA[
-	debug weaving 'HelloWorld'
-        ]]></programlisting>
-
-		<para> However this does not mean that advice has actually been woven into
-		your class merely that the class has been passed to the weaver. To determine
-		whether your pointcuts match you can use the <literal>-showWeaveInfo</literal>
-		option which will cause a message to be issued each time a piece of advice is woven: </para>
-
-        <programlisting><![CDATA[
-	weaveinfo Join point 'method-execution(void HelloWorld.main(java.lang.String[]))' ...
-		]]></programlisting>
-
-        <sect2 id="configuration" xreflabel="configuration">
-            <title>Configuration</title>
+        <para>
+            Messages point out potential problems in the input program; some
+            are clearly problems (errors), but many more may depend on what
+            the programmer intends.  To keep the noise down, the latter are treated
+            as warnings that can be ignored by the programmer or information
+            hidden from the programmer.  However, when investigating
+            unexpected behavior, it's helpful to show them.  This describes how
+            to configure messages, presents some problem scenarios when
+            compiling or doing load-time weaving, and summarizes some of the 
+            more relevant messages.
+        </para>
+        <sect2 id="messages-introduction-config" 
+            xreflabel="messages-configuration">
+            <title>Configuring Messages</title>
+            <para>
+                The compiler offers <literal>-verbose</literal>, 
+                <literal>-warning</literal>, and <literal>-XLint</literal> options 
+                when invoked using the command-line, Ant, or embedded in an IDE.  
+                All options are listed in the AspectJ Development Environment Guide 
+                sections for 
+                <ulink url="../devguide/ajc-ref.html">Ajc</ulink> and 
+                <ulink url="../devguide/antTasks-iajc.html">Ant Tasks</ulink>.
+                The <ulink url="../devguide/ltw.html">Load-time Weaving</ulink> 
+                section describes how to use XML configuration files and
+                system properties to pass options to the weaver.  (You can also
+                pass options to the weaver using system properties in build-
+                time weaving.) 
+                The <literal>-verbose</literal> option has the effect of including
+                messages level "info", which are normally ignored.
+                Both <literal>warning</literal> and <literal>XLint</literal>
+                enable you to identify specific messages to emit, but warning 
+                messages tend to be the same provided by the underlying Eclipse 
+                JDT (Java) compiler, while XLint messages are emitted by the 
+                AspectJ compiler or weaver.  Obviously, during load-time weaving
+                only weaver messages will be emitted.  Similarly, if aspects
+                are compiled but not woven, then only compiler messages will be
+                emitted.  However, the usual case for the compiler/weaver working
+                at build time is to emit both compiler and weaver messages.
+            </para>
             
-            <para> The table below lists the options used to control AspectJ messages. The method
+            <para> The table below lists some options used to control AspectJ messages. The method
             of configuration depends on your environment so refer to the relevant 
             documentation for 
             <ulink url="../devguide/ajc-ref.html">ajc</ulink>, 
-            <ulink url="../devguide/antTasks-iajc.html#antTasks-iajc-options">Ant</ulink> or 
-            <ulink url="../devguide/ltw-configuration.html#weaver-options">LTW</ulink>. </para>
+            <ulink url="../devguide/.html#antTasks-iajc-options">Ant</ulink> or 
+            <ulink url="../devguide/ltw-configuration.html#weaver-options">LTW</ulink>. 
+            </para>
             <informaltable>
                 <tgroup cols="2">
                     <thead>
@@ -71,6 +75,8 @@
                             <entry>
                             	(Load-time weaving only). Show debugging messages such as
                             	which classes are being woven or those that are excluded.
+                                (This is not related to the compiler -g option to
+                                include debug information in the output .class files.)
                             </entry>
                         </row>
                         <row>
@@ -89,47 +95,65 @@
                             	Control level of lint messages.
                             </entry>
                         </row>
-                    </tbody>
-                </tgroup>
-            </informaltable>
-            
-            <para> The table below lists some useful <literal>-Xlint</literal> messages. </para>
-            <informaltable>
-                <tgroup cols="3">
-                    <thead>
                         <row>
-                            <entry>Message</entry>
-                            <entry>Default</entry>
-                            <entry>Description</entry>
+                            <entry>
+                                <literal>messageHolderClass</literal>
+                            </entry>
+                            <entry>
+                            	In Ant tasks, specify the class to receive all messages.
+                                See 
+                                <ulink url="../devguide/antTasks-iajc.html#antTasks-iajc-options">
+                                iajc task options</ulink>.
+                            </entry>
                         </row>
-                    </thead>
-                    <tbody>
                         <row>
                             <entry>
-                                <literal>aspectExcludedByConfiguration</literal>
+                                <literal>rg.aspectj.tools.Main.setMessageHolder(..)</literal>
                             </entry>
                             <entry>
-                                <literal>ignore</literal>
+                            	Programmatic access for setting the message holder
+                                outside of Ant.
                             </entry>
+                        </row>
+                        <row>
                             <entry>
-                            	If an aspect is not being woven, despite being
-                            	registered, it could be that it has been excluded
-                            	by either an <literal>include</literal> or <literal>exclude</literal> 
-                            	element in the 
-                            	<literal>aspects</literal> section of <literal>META-INF/aop.xml</literal>.
-                            	Enable this message to determine whether an aspect has
-                            	been excluded.
+                                <literal>org.aspectj.weaving.messages</literal>
+                            </entry>
+                            <entry>
+                            	Set this system property to redirect compiler/weaver
+                                messages to logging facilities, as described in
+                                <xref linkend="trace-configuration"/>.
+                            </entry>
+                        </row>
+                        <row>
+                            <entry>
+                                <literal>@SuppressAjWarnings</literal>
+                            </entry>
+                            <entry>
+                            	Include this is Java 5 code to suppress AspectJ
+                                warnings associated with the next line of code.
                             </entry>
                         </row>
                     </tbody>
                 </tgroup>
             </informaltable>
-        
-            <para>  </para>
+        </sect2>        
+    </sect1>        
+    <sect1 id="messages-scenarios">
+        <title>Message scenarios</title>
+    
+        <sect2 id="messages-scenarios-ct">
+            <title>Compile-time weaving scenarios</title>
+            <sect3 id="messages-scenarios-ct-adviceNotWoven">
+                <title>Advice not woven</title>
+                <para>This means that the pointcut for the advice did not match,
+                and it should be debugged as described in 
+                    <xref linkend="pointcuts"/>.</para>
+                </sect3>
         </sect2>
-
-        <sect2 id="examples" xreflabel="examples">
-            <title>Examples</title>
+        
+        <sect2 id="messages-scenarios-ltw">
+            <title>Load-time weaving scenarios</title>
         
             <para> You can use <literal>META-INF/aop.xml</literal> to control which
             messages are produced during LTW. The following example will produce
@@ -143,7 +167,7 @@
 	</aspectj>
 			]]></programlisting>
         
-            <para> Notice that you are told exactly which <literal>META-INF/aop.xml</literal> 
+            <para>The messages indicate which <literal>META-INF/aop.xml</literal> 
             configurations file(s) are being used. Each message is also preceeded by the 
             name of the defining class loader associated with weaver. You can use this
             information in a large system to distinguish between different applications each
@@ -157,6 +181,147 @@
 [AppClassLoader@92e78c] info register aspect ExceptionHandler
 [AppClassLoader@92e78c] info processing reweavable type ExceptionHandler: ExceptionHandler.aj
 			]]></programlisting>
+            
+            <sect3 id="messages-scenarios-ltw-adviceNotWoven">
+                <title>Advice not woven</title>
+        <para> It is often difficult to determine, especially when using load-time weaving (LTW),
+		why advice has not been woven. Here is a quick guide to the messages to
+		look for. Firstly if you use the <literal>-verbose</literal> option you 
+		should see the following message when your aspect is registered: </para>
+
+        <programlisting><![CDATA[
+	info register aspect MyAspect
+        ]]></programlisting>
+
+		<para> Secondly if you use the <literal>-debug</literal> option you should 
+		see a message indicating that you class is being woven: </para>
+
+        <programlisting><![CDATA[
+	debug weaving 'HelloWorld'
+        ]]></programlisting>
+
+		<para> However this does not mean that advice has actually been woven into
+		your class; it says that the class has been passed to the weaver. To determine
+		whether your pointcuts match you can use the <literal>-showWeaveInfo</literal>
+		option which will cause a message to be issued each time a join point is woven: </para>
+
+        <programlisting><![CDATA[
+	weaveinfo Join point 'method-execution(void HelloWorld.main(java.lang.String[]))' ...
+		]]></programlisting>
+        
+        <para>If advice should be woven at this join point, you should get a 
+            corresponding message.</para>
+            </sect3>
         </sect2>
     </sect1>
+            
+    <sect1 id="messages-xlint">
+        <title>Lint messages</title>
+                                <para> 
+                The table below lists some useful <literal>-Xlint</literal> messages. </para>
+            <informaltable>
+                <tgroup cols="3">
+                    <thead>
+                        <row>
+                            <entry>Message</entry>
+                            <entry>Default</entry>
+                            <entry>Description</entry>
+                        </row>
+                    </thead>
+                    <tbody>
+                        <row>
+                            <entry>
+                                <literal>aspectExcludedByConfiguration</literal>
+                            </entry>
+                            <entry>
+                                <literal>ignore</literal>
+                            </entry>
+                            <entry>
+                            	If an aspect is not being woven, despite being
+                            	registered, it could be that it has been excluded
+                            	by either an <literal>include</literal> or <literal>exclude</literal> 
+                            	element in the 
+                            	<literal>aspects</literal> section of <literal>META-INF/aop.xml</literal>.
+                            	Enable this message to determine whether an aspect has
+                            	been excluded.
+                            </entry>
+                        </row>
+                        <row>
+                            <entry>
+                                <literal>adviceDidNotMatch</literal>
+                            </entry>
+                            <entry>
+                                <literal>warning</literal>
+                            </entry>
+                            <entry>
+                            	Issued when advice did not potentially affect any join points.
+                                This means the corresponding pointcut did not match any join
+                                points in the program.  This may be valid e.g., in library 
+                                aspects or code picking up error conditions, but often the
+                                programmer simply made a mistake in the pointcut.  The best
+                                approach is to debug the pointcut.
+                            </entry>
+                        </row>
+                        <row>
+                            <entry>
+                                <literal>invalidAbsoluteTypeName</literal>
+                            </entry>
+                            <entry>
+                                <literal>warning</literal>
+                            </entry>
+                            <entry>
+                            	Issued when an exact type in a pointcut does not match any type
+                                in the system.  Note that this can interact with the rules for
+                                resolving simple types, which permit unqualified names if they
+                                are imported.
+                            </entry>
+                        </row>
+                        <row>
+                            <entry>
+                                <literal>typeNotExposedToWeaver</literal>
+                            </entry>
+                            <entry>
+                                <literal>warning</literal>
+                            </entry>
+                            <entry>
+                            	This means that a type which could be affected by an aspect
+                                is not available for weaving.  This happens when a class on
+                                the classpath should be woven.
+                            </entry>
+                        </row>
+                        <row>
+                            <entry>
+                                <literal>runtimeExceptionNotSoftened</literal>
+                            </entry>
+                            <entry>
+                                <literal>warning</literal>
+                            </entry>
+                            <entry>
+                            	Before AspectJ 5, declare soft used to soften runtime exceptions
+                                (unnecessarily).  Since then, it does not but does issue this 
+                                warning in case the programmer did intend for the exception
+                                to be wrapped.
+                            </entry>
+                        </row>
+                        <row>
+                            <entry>
+                                <literal>unmatchedSuperTypeInCall</literal>
+                            </entry>
+                            <entry>
+                                <literal>warning</literal>
+                            </entry>
+                            <entry>
+                            	Issued when a call pointcut specifies a defining type which
+                                is not matched at the call site (where the declared type of
+                                the reference is used, not the actual runtime type).  Most
+                                people should use
+                                'target(Foo) &amp;&amp; call(void foo())'
+                                instead.
+                            </entry>
+                        </row>
+                    </tbody>
+                </tgroup>
+            </informaltable>
+    </sect1>
+   
 </chapter>
diff --git a/docs/pdGuideDB/pdguide.xml b/docs/pdGuideDB/pdguide.xml
index dab3070bf..5581d5395 100644
--- a/docs/pdGuideDB/pdguide.xml
+++ b/docs/pdGuideDB/pdguide.xml
@@ -4,6 +4,7 @@
                       "../../lib/docbook/docbook-dtd/docbookx.dtd"
 [
 <!ENTITY messages               SYSTEM "messages.xml">
+<!ENTITY pointcuts              SYSTEM "pointcuts.xml">
 <!ENTITY trace                  SYSTEM "trace.xml">
 <!ENTITY ajcore                 SYSTEM "ajcore.xml">
 <!ENTITY ltwdump                SYSTEM "ltwdump.xml">
@@ -28,16 +29,46 @@
 
     <abstract>
       <para>
-        This guide describes how to gather and interpret information from the AspectJ compiler
-        to diagnosing problems in AspectJ programs, configuring the load-time weaving
-        framework or reporting bugs on Bugzilla. Some information e.g. messages is intended to
-        help you solve coding or configuration problems. Other information is intended to be
-        be used by the AspectJ team when trying to fix bugs.
+          This describes how to configure the AspectJ compiler/weaver to provide
+          information for diagnosing problems in the input programs or in the 
+          compiler/weaver itself.
       </para>
-    </abstract>
+      <para>
+          The AspectJ compiler and weaver can provide lots of information for diagnosing
+          problems in building AspectJ programs.  For problems in the input program,
+          there are a number of default warning and error messages and many 
+          configurable "lint" messages, all of which can be emitted normally, 
+          logged using standard facilities, or intercepted programmatically. 
+          These are discussed in <xref linkend="messages"/>.  Since most errors
+          relate to writing pointcuts incorrectly, there is a section on 
+          <xref linkend="pointcuts"/>.
+      </para>
+      <para>
+          For problems with the compiler/weaver itself, there are three facilities
+          that enable the AspectJ developers to resolve bugs even when it is
+          too hard to deliver a reproducible test case: 
+        <orderedlist>
+            <listitem><para><xref linkend="trace"/> can be enabled to track progress up to the time of a failure;</para></listitem>
+            <listitem><para><xref linkend="ajcore"/> can give a relatively complete picture of the state of 
+          the world at the time of a failure; and </para></listitem>
+            <listitem><para><xref linkend="ltwdump"/> is a way to capture both 
+                input and output classes during load-time weaving.
+          </para></listitem>
+        </orderedlist>
+          </para>
+      <para>
+          This guide describes how to configure messages to get the right information
+          and how to configure traces, dumps, and core files.  Although the compiler/weaver
+          operates in roughly three modes (from the command-line, embedded in an IDE, 
+          and enabled as load-time weaving), the principles are basically the same for 
+          all modes.  The differences lie in how to set up diagnostics and what 
+          information is likely to be relevant.   
+      </para>        
+    </abstract>            
   </bookinfo>
   
   &messages;
+  &pointcuts;
   &ajcore;
   &trace;
   &ltwdump;
diff --git a/docs/pdGuideDB/pointcuts.xml b/docs/pdGuideDB/pointcuts.xml
new file mode 100644
index 000000000..ecf3cf662
--- /dev/null
+++ b/docs/pdGuideDB/pointcuts.xml
@@ -0,0 +1,162 @@
+<chapter id="pointcuts" xreflabel="Debugging Pointcuts">
+    <title>Debugging Pointcuts</title>
+    <sect1 id="pointcuts-introduction">
+    <title>Introduction</title>
+    
+    <para> 
+        This section describes how to write and debug pointcuts
+        using the usual approach of iteration and decomposition.
+        New users are often stumped when their advice does not match.
+        That means the pointcut doesn't match; they rewrite the
+        pointcut and it still doesn't match, with no new information.
+        This can be frustrating if each iteration involves building,
+        deploying, and testing a complex application.  Learning to
+        break it down, particularly into parts that can be checked
+        at compile-time, can save a lot of time.
+    </para>
+    </sect1>    
+    
+    <sect1 id="pointcuts-debugging">
+    <title>Debugging pointcuts</title>
+    <para>
+Go at it top-down and then bottom-up.  Top-down, draft significant
+aspects by first writing the comments to specify responsibilities.
+Advice responsibility usually takes the form, "When X, do Y."
+Pointcut responsibility for "When X" often takes the form,
+"When [join points] [in locations] [are ...]".  These []'s often
+translate to named pointcuts (like `libraryCalls() &amp;&amp; within(Client)
+&amp;&amp; args(Context)`) which form a semantic bridge to the plain-text
+meaning in a comment (e.g., `// when the client passes only context into
+the library`).        
+This gets you to a point where you can debug the parts of the
+pointcut independently.
+    </para>
+    <para>
+Bottom up (to build each part), consider each primitive pointcut
+designator (PCD), then the composition, and then any implicit
+constraints:
+    <orderedlist>
+    <listitem><para>
+What kinds of join points should it match? (constructor-call?
+field-get?)?  This translates to using the kinded pointcuts
+(`call(..)`, `get(..)`, etc.).
+    </para></listitem>
+    <listitem><para>
+Are these restricted to being lexically within something?  This
+translates to using `within{code}(..)`.  If this is true, it should
+always be used, to speed up weaving.
+    </para></listitem>
+    <listitem><para>
+What runtime constraints and context should be true and available at
+each join point?  This translates to `this()`, `target()`, `args()`,
+`cflow{below}()` and `if(..)`.
+    </para></listitem>
+    <listitem><para>
+Are there any advice or implementation limitations at issue?  This
+involves knowing the few constraints on AspectJ imposed by Java bytecode 
+as listed in the AspectJ Programming Guide section on 
+        <ulink url="../progguide/implementation.html">Implementation Notes</ulink>.
+    </para></listitem>
+    </orderedlist>
+    </para>
+    <para>
+       It's much faster to iterate a pointcut at compile-time
+        using declare warning (even better, some errors are identified
+        at parse-time in the latest versions of AJDT).
+        Start with the parts of the pointcut
+        that are staticly-determinable (i.e., they do not involve
+        the runtime PCD's listed above).  If compiles themselves
+        take too long because of all the AspectJ weaving, then
+        try to only include the debugging aspect with the prototype
+        pointcut, and limit the scope using <literal>within(..)</literal>.
+    </para>
+    <para>
+        Some mistakes in primitive pointcuts:
+        <itemizedlist>
+<listitem><para>
+`this(Foo) &amp;&amp; execution(static * *(..))`: There is no `this` in a static
+context, so `this()` or `target()` should not be used in a static
+context or when targetting a static context (respectively).  This
+happens most often when you want to say things like "all calls to Foo from Bar"
+and you only pick out calls to instance methods of Foo
+or you try to pick out calls from static methods of Bar.
+</para></listitem>
+<listitem><para>
+`target(Foo) &amp;&amp;  call(new(..)`: This will never match.  In
+constructor-call join points, there is no target because the object
+has not been created yet. 
+</para></listitem>
+<listitem><para>
+`call(* Foo.*(..))`: `Foo` refers to the compile-time type of the
+invoking reference, not the implementing class.  In Java before 1.4,
+the compile-time type was rendered as the defining type, not the
+reference type; this was corrected in 1.4 (as shown when using ajc
+with the -1.4 flag)  Most people should use `target(Foo) &amp;&amp;  call(...)`.
+</para></listitem>
+<listitem><para>
+`execution(* Foo.bar(..))`: An execution join point for Foo is
+always within Foo, so this won't pick out any overrides of bar(..).
+Use `target(Foo) &amp;&amp;  execution(* bar(..))` for instance methods.
+</para></listitem>
+<listitem><para>
+`within(Foo)`: anonymous types are not known at weave-time to be
+within the lexically-enclosing type (a limitation of Java bytecode).
+</para></listitem>
+        </itemizedlist>
+    </para>
+    <para>
+        Some mistakes in composition:
+        <itemizedlist>
+<listitem><para>
+`call(* foo(Bar, Foo)) &amp;&amp; args(Foo)`: This will never match.
+The parameters in `args(..)` are position-dependent, so `args(Foo)` only picks
+ out join points where there is only one argument possible, of type Foo.
+Use the indeterminate-arguments operator '..' as needed, e.g., `args(Foo, ..)`.
+</para></listitem>
+<listitem><para>
+`call(* foo()) &amp;&amp; execution(* foo())`: This will never match.  Each
+pointcut must be true at each join point matched.  For a union of different
+kinds of join points (here, call or execution), use '||'.
+E.g., to match both method-call and field-get join points, use 
+    `call(* ...) || get(...)`.
+</para></listitem>
+</itemizedlist>
+    </para>
+    <para>
+        Some mistakes in implicit advice constraints:
+        <itemizedlist>
+<listitem><para>
+`after () returning (Foo foo) : ...`: after advice can bind the
+returned object or exception thrown.  That effectively acts like
+`target()`, `this()`, or `args()` in restricting when the advice
+runs based on the runtime type of the bound object, even though it is
+not explicitly part of the pointcut.
+</para></listitem>
+</itemizedlist>
+    </para>
+    <para>
+        Some mistakes in implementation requirements:
+        <itemizedlist>
+<listitem><para>
+`ajc` has to control the code for a join point in order to implement
+the join point.  This translates to an implicit `within({code under
+the control of the compiler})` for all join points, with additional
+caveat for some join points.  Take exception handlers, for example:
+there is no way to be sure from the bytecode where the original handler
+ends, so `ajc` can't implement after advice on handler join points.
+(Since these are on a per-join-point basis, they should be considered
+for each corresponding primitive pointcut designator.)  Unlike the
+mistakes with the primitive PCDs above, the compiler will emit an
+error for these caveats.
+</para></listitem>
+<listitem><para>
+`call(@SuperAnnotation Subclass.meth()`: Annotations are not inherited
+by default, so e.g., if the pointcut specifies an annotation, then 
+subclass implementations of that method will not be matched.
+</para></listitem>
+</itemizedlist>
+    </para>
+
+
+    </sect1>
+</chapter>
diff --git a/docs/pdGuideDB/trace.xml b/docs/pdGuideDB/trace.xml
index 382d87842..21cc7d796 100644
--- a/docs/pdGuideDB/trace.xml
+++ b/docs/pdGuideDB/trace.xml
@@ -1,30 +1,39 @@
-<chapter id="trace" xreflabel="Trace">
+<chapter id="trace" xreflabel="Tracing">
     <title>Tracing</title>
     
     <sect1 id="trace-introduction">
         <title>Introduction</title>
         
-        <para> The usual approach to opening a report on Bugzilla is to describe the symptoms of the 
+        <para> 
+            The AspectJ developers have instrumented the compiler/weaver with
+            many "trace" messages for their own debugging use.  These remain in
+            the production releases because tracing helps when it is hard to 
+            isolate the problem in a test case.  This sections describes how
+            to enable tracing so you can provide trace information on bug reports.
+        </para> 
+        <para> 
+            The usual approach to opening a report on Bugzilla is to describe the symptoms of the 
         problem and attach a simple testcase. This allows the AspectJ team to try and reproduce the problem in
         an attempt to fix it as well as improve the test suite. Unfortunately it may not be possible
         to produce such a testcase either because your program is too large or is commercially sensitive. Alternatively 
         the problem may relate to your specific environment where AspectJ is being used and will not be
-        reproducible by the AspectJ team. In each of these situations you may be asked to produce a
+        reproducible by the AspectJ team. In each of these situations you can produce a
         trace of the compiler when the problem occurs instead. This can then be attached to the bug report. </para>
 
-        <sect2 id="configuration" xreflabel="configuration">
-            <title>Configuration</title>
+        <sect2 id="trace-configuration" xreflabel="Configuring Tracing">
+            <title>Configuring Tracing</title>
         
             <para> When available (Java 5 or later) AspectJ will use the 
-            <literal>java.util.logging</literal>
-            <ulink url="http://java.sun.com/j2se/1.5.0/docs/guide/logging/index.html">infrastructure</ulink> 
-            that is configured using a logging.properties file. By default only error
-            and fatal events will be logged but less severe warnings as well as fine grained
+            <ulink url="http://java.sun.com/j2se/1.5.0/docs/guide/logging/index.html">
+            java.util.logging</ulink> infrastructure
+            configured using a <literal>logging.properties</literal> file. By default only error
+            and fatal events will be logged but less severe warnings as well as fine-grained
             method entry and exit events can be obtained using the appropriate configuration. All
             regular compiler messages can also be logged through the infrastructure by setting the
             <literal>org.aspectj.weaving.messages</literal> System property. </para>
             
-            <para> If you are using a JDK 1.4 or earlier AspectJ will use a simple built-in trace
+            <para> If you are running the AspectJ compiler/weaver under JDK 1.4 or earlier, 
+                AspectJ will use a simple built-in trace
             infrastructure that logs to stderr. This is enabled by setting the 
             <literal>org.aspectj.weaving.tracing.enabled</literal> System property. You may also override
             the default behaviour or provide your own trace implementation using the
@@ -86,7 +95,7 @@
             </informaltable>
         </sect2>
 
-        <sect2 id="examples" xreflabel="examples">
+        <sect2 id="trace-examples" xreflabel="trace-examples">
             <title>Examples</title>
         
             <para> Using <literal>-Dorg.aspectj.tracing.factory=default</literal>