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

[Mike Duigou]

Hello all;

Here's the promised results of the survey. With 10 responses 7 favoured the "before @param" option and 3 favoured the "@after throws" option. Here are the survey text comments, "-", with my notes, "--", following each.

- "@apiNote should be removed, anything it has to say should be included in the normal text of the constructor or method. @implNote should be used sparingly it adds little value. In any case it should be formatted to be part of the method description not an indented block following the normal javadoc text"

-- @apiNote is intended for informational API text. This will probably be mostly examples. Existing examples could be converted to "API Notes"

-- @implNote is expected to be the least used of the tags. It's include to square out the matrix of api/impl spec/note.

- "API Notes is not shown after the @throws tag in sample #2. It should be."

-- The positioning before @param was intentional. API notes will mostly be reclassifications of existing examples which are currently before @param.

- "@implSpec has to be shown. Its normative!"

-- Agreed, the question at hand is its position.

- "@implSpec and @implNote should be rendered in a smaller font, and collapsed by default"

-- Outside the scope of this request. The javadoc html doclet defines the presentation of elements.

- "I want to know. Don't hide it."

-- Agreed, the question at hand is its position.

- "Historically, implementation notes have been in the "main section". These tags just formalize this. Also, the sections labeled by them are likely to be long; historically, the "little" ones (@param, @return, @throws, @since) are at the end. So I think these pretty clearly go after the main spec and before the @param."

-- (no response)


Thank you all for your responses and feedback on this issue. I believe this leaves us with the @implSpec/@implNote being presented before the @param tag and this is the direction I will proceed for now. There's still time in the Java 8 schedule to refine the placement and presentation should further hands-on experience lead us to other conclusions. One outstanding issue is poor html presentation of the @apiNote/@implSpec/@implNote in class and package docs--this is still to be followed up on in a separate issue.

I will wait 24 hours for any vetos to pushing this change.

Mike


On Apr 22 2013, at 18:15 , Mike Duigou wrote:

> Hi All;
> 
> I've produced a sample of Javadoc with the @implSpec/@implNote tag output before and after the @param section.
> 
> http://cr.openjdk.java.net/~mduigou/JDK-8008632/implBefore/
> 
> http://cr.openjdk.java.net/~mduigou/JDK-8008632/implAfter/
> 
> Take a look at these samples and see if you feel strongly about one or the other. Then visit:
> 
> https://www.surveymonkey.com/s/CQ8S7R8
> 
> I will run the survey for a couple of days and report the results here.
> 
> Thanks
> 
> Mike
> 
> 
> On Apr 18 2013, at 11:58 , roger riggs wrote:
> 
>> Hi Mike,
>> 
>> Sorry for so many comments on this but I have one more.
>> 
>> I don't think the order of @implSpec, @implNote is optimal.  As a developer I want to read
>> the javadoc and see the description, parameters, returns, etc.
>> 
>> I don't want to see the implementation spec or notes.  Maybe they are more
>> important in default methods but in ordinary methods, they are important
>> only when the details matter.
>> 
>> I would push @implSpec and @implNote down after @throws.
>> 
>> 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.
>>>>>>> 
>>>>>>> 
>>>>>>> 
>>>>>>> 
>> 
>