Request for Review : CR#8004015 : [final (?) pass] Add interface extends and defaults for basic functional interfaces (original) (raw)

Joe Bowbeer joe.bowbeer at gmail.com
Thu Dec 6 19:45:48 PST 2012

Ah, yes, I misunderstood the intent. Sorry.

I agree that the null wording should be minimized, esp. in the parameter descriptions.

The @throws NPE descriptions make it clear in every occurrence that nulls are prevented, which I like in this case, but do not distract the casual reader.

On Thu, Dec 6, 2012 at 6:02 PM, David Holmes <david.holmes at oracle.com>wrote:

Joe,

On 7/12/2012 2:18 AM, Joe Bowbeer wrote: The documentation for Collection.add is not a reasonable model to emulate?

http://docs.oracle.com/javase/6/docs/api/java/util/ Collection.html#add(E)<http://docs.oracle.com/javase/6/docs/api/java/util/Collection.html#add(E)> It is written from the standpoint that nulls are OK, but notes that some implementations might barf, and lists NPE among the possible exceptions. The difference here is that the intent is for nulls to be prohibited - full stop. In other places "we" avoid the API clutter by making broad statements regarding null handling "Unless otherwise stated null parameters to method or constructors of this class will result in NullPointerException being thrown". In some places we even handle this at the package doc level. Perhaps we should do the same here? Otherwise, the "right way" IMHO to indicate this is via @throws, not additional commentary on @param. Again YMMV. David ----- I think that's the right approach for streams as well. In a wide range of popular APIs, there are lots of methods that return null, and it is these nulls that are the most likely to show up in functionally-constructed streams. Java programmers do have the notion that nulls might not be allowed everywhere, and will look to the javadoc for clarification.

On Thu, Dec 6, 2012 at 7:56 AM, Mike Duigou<mike.duigou at oracle.com> wrote: Something seems entirely out of balance regarding handling of null. If a methods says that it takes a reference type then why ever might it be assumed that null is permitted? It feels more than a bit like we are adding "no naked people" stickers to every building entrance and "do not insert fingers" to every electrical outlet. The "@throws NPE" are yet another layer of "Violators will be arrested" or "You will be electrocuted" stickers. It seems entirely wrongheaded to assume that null could be passed in place of a valid reference unless explicitly and categorically forbidden. Accepting null should be considered extraordinary and worthy of mention only when it occurs. Being rare it would also be a lot easier to document. So really, why mention null at all? Mike On Dec 6 2012, at 04:47 , David Holmes wrote: Stephen, I believe that exceptions thrown should be identified using @throws - not implied.

I think @param is for giving the basic description of a parameter not for explaining the semantics, or what different values of the parameter mean. YMMV David On 6/12/2012 8:23 PM, Stephen Colebourne wrote: On 6 December 2012 06:06, David Holmes<david.holmes at oracle.com**> wrote: On 6/12/2012 4:20 AM, Mike Duigou wrote:

I have updated webrev again to fix some reported javadoc technical issues and added null handling specification to the {Int|Double|Long}Supplier. http://cr.openjdk.java.net/**mduigou/8004015/2/webrev/<http://cr.openjdk.java.net/mduigou/8004015/2/webrev/>

http://cr.openjdk.java.net/~mduigou/8004015/2/specdiff/ java/util/function/package-**summary.html<http://cr.openjdk.java.net/~mduigou/8004015/2/specdiff/java/util/function/package-summary.html> I believe that this iteration is complete (or very nearly so). Sorry to be a pain but this: left - the left operand, must be non-null doesn't tell you what happens if it is null. Is it not better to simply have: @param left the left operand @param right the right operand @throws NullPointerException if either left or right are null Whereas I use: @param left the left operand, not null @param right the right operand, not null There is an element of taste here. As I wrote up http://blog.joda.org/2012/11/**javadoc-coding-standards.html<http://blog.joda.org/2012/11/javadoc-coding-standards.html> Javadoc is read as source code as often as it is read as HTML. Thus, not overly cluttering is important. IMO, the @throws NPE is implied by the assertion of "not null" or "must be non-null". More importantly, the use of @param scales better. For example, there is often a case where null is treated as a default or special value. The Javadoc would then look something like @param left the left operand, null treated as zero @param right the right operand, null treated as zero This kind of information belongs with the @param, and for consistency it is much better to also have the "not null" aspect on the @param as well. (Everything together is easier for developers to parse) In summary, while I prefer my "not null" to Mike's "must be non-null", what is proposed is fine, and better than your (David's) proposal. Stephen -------------- next part -------------- An HTML attachment was scrubbed... URL: http://mail.openjdk.java.net/pipermail/lambda-libs-spec-experts/attachments/20121206/5efc65f0/attachment.html

More information about the lambda-libs-spec-experts mailing list