doc changes for @Around... wip

1 files changed, 20 insertions, 0 deletions

diff --git a/docs/adk15ProgGuideDB/ataspectj.xml b/docs/adk15ProgGuideDB/ataspectj.xml
index 4faa14548..df4cdb638 100644
--- 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>