RFR : CR8004015 : Add parent interfaces and default methods to basic functional interfaces

[Mike Duigou]

On Dec 16 2012, at 20:18 , David Holmes wrote:

> On 15/12/2012 4:58 AM, Mike Duigou wrote:
>> 
>> On Dec 13 2012, at 22:28 , David Holmes wrote:
>> 
>>>> I have added @throws NPE for a number of the default methods. We won't be including @throws NPE in all cases where null is disallowed because when the @throws NPE is declared the API is required to throw NPE in that circumstance. So for cases where the NPE is "naturally" thrown or that aren't performance sensitive we will likely add @throws NPE declarations but for performance sensitive methods we won't be adding explicit null checks to match a @throws NPE specification. There's a tradeoff here in some cases. Please feel free to quibble about specific cases as they occur. :-)
>>> 
>>> That doesn't make sense to me. The throwing of the NPE is intended to be part of the specification not an implementation choice. Further @param foo non-null, is just as binding on implementations as @throws NPE if foo is null. ???
>> 
>> An "@param foo non-null" by itself is not considered normative because it doesn't document what happens when null is passed. So it ends up being advisory only. An "@throws NPE" is considered normative and the implementation must throw in all circumstances described.
> 
> Aside: that is an interesting interpretation but from whence does it come?

From the TCK/JCK team. In communications with them to clarify the specification 

> It is non-normative by definition because it is incomplete?

Yes. If a constraint is specified then it is only testable to the extent that the outcome of is also described.

> Or is it just non-normative because it is an @param tag?

No.

> 
>> (Please bear with the step-by-step nature of the following sample, it's incremental pace is not meant to be insulting--it's a write-up for a general FAQ). If I have a method:
> 
> But once you add the @throws the advisory of the @param is redundant. Hence to me it is an either/or situation.

It does seem redundant to me but not entirely useless. I would prefer to not have to check the @throws declaration to know what the valid range is for a parameter. My tendency is to always try to consolidate all information about something in one place and if that's not practical then allow for some duplication.

An example recently was information about the ForkJoin common pool. I prefer to see all the characteristics of the common pool described on the documentation for commonPool() method rather than disparately on shutdown(), etc. The advantage being that collecting it into one place allows be to completely understand (OK, within limits) the characteristics of common pool. Without the consolidation I may not even be able to find all of the documentation which references the common pool. There does seem to be some value though to duplicating the information to other places where it might be relevant. It's perhaps worthwhile to note in shutdown() that it is ignored for the common pool. 

> Further the advisory, being advisory, is useless in my opinion, so not something to use regardless.

The advisories do still represent good advice for what to pass.

Mike