updated RI code and API javadoc

[Yuri Gaevsky]

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 at openjdk.java.net
> http://mail.openjdk.java.net/mailman/listinfo/mlvm-dev