From: aclement <aclement>
Date: Thu, 21 Feb 2008 01:05:35 +0000 (+0000)
Subject: 210848: better javadoc
X-Git-Tag: V1_6_0M2~45
X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=b4715bcd195773fb2321270e20458482c00b3854;p=aspectj.git

210848: better javadoc
---

diff --git a/runtime/src/org/aspectj/lang/ProceedingJoinPoint.java b/runtime/src/org/aspectj/lang/ProceedingJoinPoint.java
index 9d220358d..5bbc2df85 100644
--- a/runtime/src/org/aspectj/lang/ProceedingJoinPoint.java
+++ b/runtime/src/org/aspectj/lang/ProceedingJoinPoint.java
@@ -41,8 +41,21 @@ public interface ProceedingJoinPoint extends JoinPoint {
     /**
      * Proceed with the next advice or target method invocation
      * <p/>
-     * The given args Object[] must be in the same order and size as the advice signature but
-     * without the actual joinpoint instance
+     * <p>Unlike code style, proceed(..) in annotation style places different requirements on the 
+     * parameters passed to it.  The proceed(..) call takes, in this order:
+     * <ul>
+     * <li> If 'this()' was used in the pointcut for binding, it must be passed first in proceed(..).
+     * <li> If 'target()' was used in the pointcut for binding, it must be passed next in proceed(..) - 
+     * it will be the first argument to proceed(..) if this() was not used for binding.
+     * <li> Finally come all 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. 
+     * </ul>
+     * <p>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. 
+     * </p>
      *
      * @param args
      * @return