RFR : 8008632 : Additional JavaDoc tags @apiNote, @implSpec and @implNote for JDK API Docs
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.
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. Are you planning to provide a documentation page for these tags? This would be useful to others writing API docs in the future. One question on the webrev. You've listed "factory" and I'm not sure that I recognize this. 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. -Alan
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
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? -Alan
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
On 19/04/2013 16:13, Mike Duigou wrote:
: 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.).
Sorry, I meant @implNote where it may not always be desirable to have that show up in the generated javadoc. -Alan.
On Apr 19 2013, at 08:15 , Alan Bateman wrote:
On 19/04/2013 16:13, Mike Duigou wrote:
: 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.).
Sorry, I meant @implNote where it may not always be desirable to have that show up in the generated javadoc.
Unsure. I haven't looked at how the @implNote tag has been used. According to the definition it certainly could be. Both the @apiNote and @implNote are non-normative and could technically be removed from the spec. I have a task today of generate samples with the @implSpec and @implNote tags moved to the end of the docs rather than before @param. That thread would be a good place to have the discussion about inclusion (along with placement). Mike
-Alan.
Hi Mike, The new tags are useful. JSR 310 has a similar need and construct as @implSpec and will adopt the common tags. Some more information would be useful about the changeset; why are the pre-existing tags included in the change? Note that Oracle accessibility guidelines for html indicate that headers should use header tags <hx> </hx> to be properly navigable by accessibility tools. 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.
On Apr 18 2013, at 06:27 , roger riggs wrote:
Hi Mike,
The new tags are useful. JSR 310 has a similar need and construct as @implSpec and will adopt the common tags.
Some more information would be useful about the changeset; why are the pre-existing tags included in the change?
Sorry I had meant to mention this in my original note but forgot. The pre-existing tags are enumerated to provide ordering. Normally new tags added with -tag are appended into javadoc output. Since we wish to order the new tags before @param tags we have to provide the total ordering of all tags.
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. 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.
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 would remove the <em> explicit markup or if possible delegate to the stylesheet with a <span class= "xxx">. 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.
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.
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-su... 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.
On Apr 18 2013, at 10:56 , roger riggs wrote:
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-su...
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.
Alternatively we could submit an RFE to improve javadoc styling for simple tags in overview and package contexts. I know it generates different output for different contexts already.
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.
On Wed, Apr 17, 2013 at 4:51 PM, Mike Duigou <mike.duigou@oracle.com> wrote:
@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.
Although I have often wished for tags such as these, (and in the distant past held back from working on this myself due to difficulty), as currently implemented I fear they will only increase the confusion about subtle distinctions of normative vs. non-normative and documenting this class vs. all subclasses. There does not appear to be any documentation in the jdk itself about these tags. This email thread is the only documentation I can find. Even when only used internally, there needs to be clear documentation somewhere. Unfortunately, there is no obvious place to look for documentation on non-standard javadoc tags. The tags should be made public, since correct documentation is a need everyone has. While the tags themselves are private, their output is not. When users read: Implementation Requirements: in the javadoc, it's not at all clear what is meant - i.e. it is requirements on implementers of *this* class in any JDK, but not necessarily subclasses. We should not use the word "Requirements" unless speaking about things required of "users". Other JDK implementers are not the primary target of this documentation. It's not at all easy to do this better. Perhaps we should do away with the one-size-fits-all @implSpec expansion. It would be clearer if the spec read: The default method forEach in class Map (but not necessarily subinterfaces or subclasses) shall behave ... Perhaps there should be a lower-level @noInheritDoc tag to allow people to write such prose.
On Dec 9 2013, at 11:49 , Martin Buchholz <martinrb@google.com> wrote:
On Wed, Apr 17, 2013 at 4:51 PM, Mike Duigou <mike.duigou@oracle.com> wrote:
@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.
Although I have often wished for tags such as these, (and in the distant past held back from working on this myself due to difficulty), as currently implemented I fear they will only increase the confusion about subtle distinctions of normative vs. non-normative and documenting this class vs. all subclasses.
If this is the case then we need to tighten up the usage
There does not appear to be any documentation in the jdk itself about these tags. This email thread is the only documentation I can find. Even when only used internally, there needs to be clear documentation somewhere. Unfortunately, there is no obvious place to look for documentation on non-standard javadoc tags.
Writing up a doc page on these tags has been on my TO-DO list for quite some time. Unfortunately it hasn't bubbled to the top yet. As we get closer to Java 8 release the priority will certainly increase.
The tags should be made public, since correct documentation is a need everyone has.
There are no plans to attempt to popularize these particular tags outside of use by JDK documentation.
While the tags themselves are private, their output is not. When users read:
Implementation Requirements:
This is still changeable. "Required behaviour of all implementations:" perhaps?
in the javadoc, it's not at all clear what is meant - i.e. it is requirements on implementers of *this* class in any JDK, but not necessarily subclasses. We should not use the word "Requirements" unless speaking about things required of "users". Other JDK implementers are not the primary target of this documentation.
It's not at all easy to do this better. Perhaps we should do away with the one-size-fits-all @implSpec expansion. It would be clearer if the spec read:
The default method forEach in class Map (but not necessarily subinterfaces or subclasses) shall behave ...
In part the tags were added to avoid the unfortunate inclusion of implementation specifics into the functional description.
Perhaps there should be a lower-level @noInheritDoc tag to allow people to write such prose.
That is how these are effectively being used. Mike
On Mon, Dec 9, 2013 at 3:58 PM, Mike Duigou <mike.duigou@oracle.com> wrote:
While the tags themselves are private, their output is not. When users read:
Implementation Requirements:
This is still changeable. "Required behaviour of all implementations:" perhaps?
I think this is not moving us towards clarity. "Required behaviour of all implementations:" actually applies more to the "regular" unlabelled documentation, since that applies to subclasses as well. Perhaps we want to get rid of words like "requirements" because they apply equally to the part not labelled "requirements"?! The key difference is that we are documenting the behavior of THIS method on THIS class. Maybe: Behavior of the default method Map.forEach: When I was musing about doing this myself years ago, I was not motivated by default methods (they didn't exist yet!) but instead by the "skeletal" implementation classes like AbstractMap. Hopefully we can @implSpec them for jdk8?
participants (4)
-
Alan Bateman
-
Martin Buchholz
-
Mike Duigou
-
roger riggs