Proposal for review: @specification javadoc tag

[Jonathan Gibbons]

We should make sure that any new taglet like this does not generate any 
new warnings in the build about undefined taglets.

-- Jon

On 06/03/2010 02:40 PM, Joe Darcy wrote:
> Greetings.
>
> The JDK documentation makes references to various external 
> specifications, including RFCs, etc. [1]  At times it would be helpful 
> if these references could be reliably found and tracked.  To ease this 
> task for JDK 7, I'm proposing a new @specification javadoc tag with 
> two variations:
>
> {@specification text}
> {@specification URL text}
>
> In the standard doclet, the former would just render as
>  text
> and the latter as
> <a href="URL">text</a>
>
> A helper doclet could then be written to look over all the sources and 
> generate an external specification report.
>
> The exact design of the tags might be improved by some tweaking; the 
> standard doclet has some logic to recognize URLs from the @see tag so 
> the second version might be easier to implement as {@specification <a 
> href="URL">text</a>}.  However, I think the basic capabilities needed 
> to facilitate tracking specifications are the ability to refer to a 
> specification by name only and the ability to refer to a specification 
> by name and URL.
>
> Existing external references would be changed to use the tag and any 
> new references would use the {@specification} tag as well.
>
> Comments?
>
> -Joe
>
> [1] See for example the work done for 6952701 "Use 
> http://www.ietf.org/rfc <http://www.ietf.org/rfc> for rfc references 
> in jdk public APIs."