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. >> >> >> >> >
