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