RFR (M) 8024438: JSR 292 API specification maintenance for JDK 8

[John Rose]

On Oct 2, 2013, at 12:14 PM, Christian Thalinger <christian.thalinger at oracle.com> wrote:

> src/share/classes/java/lang/invoke/MethodHandles.java:
> 
> +     *     <th><a name="equiv"></a>lookup expression</th>
> 
> Apparently the name attribute is obsolete for <a/> in HTML5:
> 
> http://dev.w3.org/html5/markup/a.html
> 
> I think they want you to use <th id="equiv">.
> 
> +     * <p style="font-size:smaller;">
> +     * <a name="privacc"></a>
> +     * <em>Discussion of private access:</em>
> 
> Same here.
> 
> +     * <h1><a name="secmgr"></a>Security manager interactions</h1>
> 
> And here.

Wow; I don't know where HTML5 fits in the javadoc story.  That might be nice to upgrade, but I'm not gonna go first:
--------
	fgrep '<a name=' $(hg loc -I src/share/classes/java -X src/share/classes/java/lang/invoke) | wc
     235    1372   23349
--------
	fgrep '<a id=' $(hg loc -I src/share/classes/java -X src/share/classes/java/lang/invoke) | wc
       0       0       0
--------
	grep '<[a-z]* id=' $(hg loc -I src/share/classes/java) | wc
      12      72    1186   ## a few CSS tags
--------
	fgrep '<a name=' $(hg loc -I src/share/classes/java/lang/invoke) | wc
       8      46     884    ## lots of people were going faster than me, officer!
--------

> +     * because the desired class member is missing, because the
> 
> Did you want an "or" before "because" like the others?

Yes, you are right.  It started out as "a, b, or c" but then got out of control.  Switching to "a, or b, or...".

> Otherwise this looks good.

Thanks.  At your verbal suggestion I also did this:

      * If the filter returns a value, the target must accept that value as
-     * its {@code pos} argument, plus any arguments not passed to the filter.
+     * its argument in position {@code pos}, preceded and/or followed by
+     * any arguments not passed to the filter.
      * If the filter returns void, the target must accept all arguments
      * not passed to the filter.

— John