John,
A couple of minor comments regarding the latest java.dyn.* javadoc:
a) "Requirements for Writing Java API Specifications" [1] specifies under the
heading "Method Specification", item number 4:
Null Argument Values - For each reference type argument, specify the
behavior when null is passed in. See two examples. NOTE: If possible,
document the general null argument behavior at the package or class
level,
such as causing a java.lang.NullPointerException to be thrown. Deviations
from this behavior can then be documented at the method level.
So, is it possible to add at the java.dyn package level something like:
Unless otherwise specified, methods in this package will throw a
NullPointerException if given a null argument.
and update javadoc for those methods which still can accept null values?
b) "How to Write Doc Comments for the Javadoc Tool" doc [2] recommends
as follows:
The description is in 3rd person declarative rather than 2nd person
imperative.
Gets the label. (preferred)
Get the label. (avoid)
Thanks,
-Yuri
[1] http://java.sun.com/j2se/javadoc/writingapispecs/index.html
[2] http://java.sun.com/j2se/javadoc/writingdoccomments/#styleguide
John Rose wrote:
> I pushed a lot more testing and implementation code for the reference
> implementation. Finally permuteArguments works, as do all the
> variations of varargs processing.
>
> Here's the updated javadoc; it's getting better:
> http://cr.openjdk.java.net/~jrose/pres/indy-javadoc-mlvm/
>
> I added filterArguments
> <http://cr.openjdk.java.net/~jrose/pres/indy-javadoc-mlvm/java/dyn/MethodHandles.html#filterArguments(java.dyn.MethodHandle,%20java.dyn.MethodHandle...)>,
>
> since I remember people asking for it during last year's Summit. Such a
> simple use case (single argument transformation with a unary function)
> is too awkward to implement in terms of foldArguments
> <http://cr.openjdk.java.net/~jrose/pres/indy-javadoc-mlvm/java/dyn/MethodHandles.html#foldArguments(java.dyn.MethodHandle,%252520java.dyn.MethodHandle)>
> (requires
> argument dropping/reordering).
>
> -- John
>
> P.S. I also added something called dynamicInvoker
> <http://cr.openjdk.java.net/~jrose/pres/indy-javadoc-mlvm/java/dyn/MethodHandles.html#dynamicInvoker(java.dyn.CallSite)>.
>
> It is a simple thing which turns a CallSite into a simulated
> invokedynamic instruction; this rounds out the Lookup.find{Static,*}
> functionality to include the new invoke instruction. Not sure if it is
> the right thing, though.
>
>
> ------------------------------------------------------------------------
>
> _______________________________________________
> mlvm-dev mailing list
> mlvm-dev@openjdk.java.net
> http://mail.openjdk.java.net/mailman/listinfo/mlvm-dev
_______________________________________________
mlvm-dev mailing list
mlvm-dev@openjdk.java.net
http://mail.openjdk.java.net/mailman/listinfo/mlvm-dev
