doc changes for @Around... wip

diff --git a/docs/adk15ProgGuideDB/ataspectj.xml b/docs/adk15ProgGuideDB/ataspectj.xml
index 4faa145487078b9b9eff5b5a41da0eff0c7f31bc..df4cdb638bac4007ba31e667a37ddae7866c3ea8 100644 (file)
--- a/docs/adk15ProgGuideDB/ataspectj.xml
+++ b/docs/adk15ProgGuideDB/ataspectj.xml
@@ -620,6 +620,26 @@
 
             <para>Note that the ProceedingJoinPoint does not need to be passed to the proceed(..) arguments.
             </para>
+            <para>In code style, the proceed method has the same signature as the advice, any reordering of
+            actual arguments to the joinpoint that is done in the advice signature must be respected.  Annotation
+            style is different.  The proceed(..) call takes, in this order:
+            <itemizedlist>
+                       <listitem>If 'this()' was used in the pointcut <emphasis>for binding</emphasis>, it must be passed first in proceed(..).
+                       </listitem>
+                       <listitem>If 'target()' was used in the pointcut <emphasis>for binding</emphasis>, it must be passed next in proceed(..) - it will be the 
+                       first argument to proceed(..) if this() was not used for binding.
+                       </listitem>
+                       <listitem>Finally come <emphasis>all</emphasis> the arguments expected at the join point, in the order they 
+                       are supplied at the join point.  Effectively the advice signature is ignored - it doesn't 
+                       matter if a subset of arguments were bound or the ordering was changed in the advice 
+                       signature, the proceed(..) calls takes all of them in the right order for the join point.
+                       </listitem>
+            </itemizedlist> 
+            </para>
+            <para>Since proceed(..) in this case takes an Object array, AspectJ cannot do as much compile time
+            checking as it can for code style.  If the rules above aren't obeyed then it will unfortunately
+            manifest as a runtime error.
+            </para>
         </sect2>
 
     </sect1>