210848: better javadoc

diff --git a/runtime/src/org/aspectj/lang/ProceedingJoinPoint.java b/runtime/src/org/aspectj/lang/ProceedingJoinPoint.java
index 9d220358def63ca984efb9f48d58f315882cec2f..5bbc2df85d4928f2cb0cb2723480e354fab66f96 100644 (file)
--- 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