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

[Mike Duigou]

On Apr 18 2013, at 05:07 , Alan Bateman wrote:

> On 18/04/2013 00:51, 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.
>> 
> @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.


> Are you planning to provide a documentation page for these tags? This would be useful to others writing API docs in the future.

I hadn't planned to though I understand it would be useful. Perhaps something for the wiki?

> One question on the webrev. You've listed "factory" and I'm not sure that I recognize this.

The @factory tag is actually present in the current javadoc tool. I don't know it's origin or why it was never documented. Only the @apiNote, @implSpec and @implNote are new tags. The pre-existing tags are enumerated along with the new tags to provide ordering for tag output. Normally the output of new tags added with -tag is placed at the end of the javadoc output after other tags. Since we wish to order the new tags before @param tags we have to provide the total ordering of all tags. 

> A long standing needs has been to distinguish static factory methods in the javadoc and perhaps this is related to that? I might have missed something of course.

Since it's never been documented or adopted for usage the @factory tag should probably be avoided for now. In particular it's output will be incomplete (no title) and not localized. We may want to remove it before someone notices it and starts to use it! :-)

Mike