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

[roger riggs]

Hi Mike,

Another wrinkle...

The "a" tag allows the tag to be used in any context package, method, 
constructor, package,
field and type and overview.  However, the predefined javadoc structure 
makes it
unsuitable for use in the package and overview.

Since javadoc groups the tags inside an indented <dl><dt><dd>... blocks it
looks quite odd.  For an example see,
http://cr.openjdk.java.net/~rriggs/javadoc-implspec-213/java/time/package-summary.html

Scan down to the "Implementation Requirements" header.
Since there is no 'end' to the @implSpec the rest of the input is indented.

I would not recommend use of any of these in the overview or package 
contexts.

Roger


On 4/18/2013 12:49 PM, Mike Duigou wrote:
> On Apr 18 2013, at 08:44 , roger riggs wrote:
>
>> Hi Mike,
>>
>> On 4/18/2013 11:01 AM, Mike Duigou wrote:
>>>> Note that Oracle accessibility guidelines for html indicate that headers
>>>> should use header tags <hx> </hx> to be properly navigable by accessibility tools.
>>> Understood. That would be a separate issue though as we have no control over the html generated by the javadoc html doclet.
>> ok, I see that javadoc defines the tag to be wrapped in <strong> xxx</strong>.
>>
>> I don't see that the additional emphasis is needed relative to the other
>> style elements of the javadoc.
> I *had* thought I was copying the JLS tag but see now that that's not the case. I no longer remember where the <em> came from.
>
>> I would remove the <em> explicit markup or if possible delegate
>> to the stylesheet with a <span class= "xxx">.
> I will remove it and allow the default formatting to be used.
>
>> Roger
>>
>>> Mike
>>>
>>>> Thanks, Roger
>>>>
>>>>
>>>> On 4/17/2013 7:51 PM, Mike Duigou wrote:
>>>>> Hello All;
>>>>>
>>>>> Some of you have noticed that the lambda streams libraries patches currently going in to the TL repo make use of special javadoc tags. There are three tags being used:
>>>>>
>>>>> @apiNote : Non-normative notes about the API. Usually used for examples.
>>>>> @implSpec : Describes required behaviour of conforming implementations. Key is that the description is not inherited.
>>>>> @implNote : Non-normative notes about the implementation. Typically used for descriptions of the behaviour. Also not inherited.
>>>>>
>>>>> The tags are used primarily by default method implementations but will be used elsewhere as well.
>>>>>
>>>>> These tags are enabled by use of the -tag feature on the javadoc tool command line. They are not proposed as standard javadoc tags and may be implemented differently in future Java releases. Since they are implemented as custom tags just for the JDK API documentation you can't automatically use them in your own code. (You can, of course, add the same command line options to your javadoc invocations if you like these tags).
>>>>>
>>>>> http://cr.openjdk.java.net/~mduigou/JDK-8008632/0/webrev/
>>>>>
>>>>> The patch enumerates the new custom tags in addition to the standard tags to ensure correct output order.
>>>>>
>>>>>
>>>>>
>>>>>