RFR : 8008632 : Additional JavaDoc tags @apiNote, @implSpec and @implNote for JDK API Docs

[Mike Duigou]

On Apr 19 2013, at 03:40 , Alan Bateman wrote:

> On 18/04/2013 16:12, Mike Duigou wrote:
>> :
>> 
>>> @implSpec is very welcome, more reasons now with the addition of default methods.
>>> 
>>> Clearly distinguishing normative from non-normative text is also been a long standing problem so having a tag to identify the non-normative text is very useful. I had to look at a few examples in the lambda/jdk repo to convince myself that both @apiNote and @implNote are needed. One thing that isn't clear to me is whether the "official" Java SE documentation should include the text tagged @implNote or not.
>> Once we got going we decided to fill out the matrix. There's no obligation to use all of the tags.
>> 
> Where @implSpec is used, then do you have a view on whether this should be filtered out of the Java SE specs?

Not as currently used, no. The @implSpec is being used to describe required behaviour of the implementation, usually defaults. ie. Conforming defaults implementations must throw ISE (or UOE, etc.).  

Mike