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

1 files changed, 232 insertions, 67 deletions

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>