Fix for Bugzilla 37899: Document or address limitations on handler pointcut/joinpoints

 * changed "Implementation Limitations" to "Implementation Notes" inside ProgGuide
 * added section on bytecode limitations, headed by handler issues.

4 files changed, 72 insertions, 7 deletions

diff --git a/docs/progGuideDB/limitations.xml b/docs/progGuideDB/implementation.xml
index 34d1cbd55..314c574f9 100644
--- a/docs/progGuideDB/limitations.xml
+++ b/docs/progGuideDB/implementation.xml
@@ -1,6 +1,9 @@
-<appendix id="limitations" xreflabel="Implementation Limitations">
+<appendix id="implementation" xreflabel="Implementation Notes">
 
-  <title>Implementation Limitations</title>
+  <title>Implementation Notes</title>
+
+<sect1>
+  <title>Compiler Notes</title>
 
   <para> 
     The initial implementations of AspectJ have all been
@@ -109,5 +112,67 @@
     be aware of the limitations of the ajc compiler you're using, but
     these limitations should not drive the design of your aspects.
   </para>
+</sect1>
+
+<sect1>
+  <title>Bytecode Notes</title>
+
+  <para>The end of exception handlers cannot reliably be found in Java
+  bytecode.  Instead of removing the handler join point entirely, the
+  current AspectJ compiler restricts what can be done with the handler
+  join point:
+  </para>
+
+  <itemizedlist>
+    <listitem>After and around advice cannot apply to handler
+    join points.</listitem>
+
+    <listitem>The control flow of a handler join point cannot be
+    detected. </listitem>
+  </itemizedlist>
+
+  <para>
+  The first of these is relatively straightforward.  If any piece of
+  after advice (returning, throwing, or "finally") would normally
+  apply to a handler join point, it will not in code output by the
+  current AspectJ compiler.  A compiler warning is generated whenever
+  this is detected to be the case.  Before advice is allowed.
+  </para>
+
+  <para> The second is that the control flow of a handler join point
+  is not picked out.  For example, the following pointcut
+  </para>
+
+<programlisting><![CDATA[
+  cflow(call(void foo()) || handler(java.io.IOException))
+]]></programlisting>
+
+  <para> will capture all join points in the control flow of a call to
+  <literal>void foo()</literal>, but it will <emphasis>not</emphasis>
+  capture those in the control flow of an
+  <literal>IOException</literal> handler.  It is equivalent to
+  <literal>cflow(call(void foo()))</literal>.  In general,
+  <literal>cflow(handler(<replaceable>Type</replaceable>))</literal>
+  will pick out no join points.
+  </para>
+
+  <para> This does not restrict programs from placing before advice on
+  handlers inside <emphasis>other</emphasis> control flows.  This
+  advice, for example, is perfectly fine:
+  </para>
+
+<programlisting><![CDATA[
+  before(): handler(java.io.IOException) && cflow(void parse()) {
+      System.out.println("about to handle an exception while parsing");
+  }
+]]></programlisting>
+
+  <para>
+    A source-code implementation of AspectJ (such as AspectJ 1.0.6) is
+    able to detect the endpoint of a handler join point, and as such
+    will likely have fewer such restrictions.
+  </para>
+
+</sect1>
 
 </appendix>
diff --git a/docs/progGuideDB/preface.xml b/docs/progGuideDB/preface.xml
index 1ad7b382b..5484fe5b3 100644
--- a/docs/progGuideDB/preface.xml
+++ b/docs/progGuideDB/preface.xml
@@ -24,7 +24,7 @@
 
     It includes appendices that give a reference to the syntax of AspectJ,
     a more formal description of AspectJ's semantics, and a description of
-    limitations allowed by AspectJ implementations.
+    notes about the AspectJ implementation.
   </para>
 
   <para>
@@ -60,7 +60,7 @@
     linkend="quick">quick reference</xref> to the language's syntax, a more
     in depth coverage of its <xref linkend="semantics">semantics</xref>,
     and a description of the latitude enjoyed by its <xref
-    linkend="limitations">implementations</xref>.
+    linkend="implementation">implementations</xref>.
   </para>
 
 </preface>
diff --git a/docs/progGuideDB/progguide.xml b/docs/progGuideDB/progguide.xml
index f23ca03b3..433d71585 100644
--- a/docs/progGuideDB/progguide.xml
+++ b/docs/progGuideDB/progguide.xml
@@ -11,7 +11,7 @@
 <!ENTITY pitfalls       SYSTEM "pitfalls.xml">
 <!ENTITY quickreference SYSTEM "quickreference.xml">
 <!ENTITY semantics      SYSTEM "semantics.xml">
-<!ENTITY limitations    SYSTEM "limitations.xml">
+<!ENTITY implementation SYSTEM "implementation.xml">
 ]>
 
 <book>
@@ -58,6 +58,6 @@
   &pitfalls;
   &quickreference;
   &semantics;
-  &limitations;
+  &implementation;
 
 </book>
diff --git a/docs/progGuideDB/semantics.xml b/docs/progGuideDB/semantics.xml
index 7b065f136..2fe8f7444 100644
--- a/docs/progGuideDB/semantics.xml
+++ b/docs/progGuideDB/semantics.xml
@@ -2591,7 +2591,7 @@
 
         <para> Both <literal>perthis</literal> and <literal>pertarget</literal>
         aspects may be affected by code the AspectJ compiler controls, as
-        discussed in the <xref linkend="limitations"/> appendix.  </para>
+        discussed in the <xref linkend="implementation"/> appendix.  </para>
       </sect3>
 
       <sect3>