Proposal for review: @specification javadoc tag

[Joe Darcy]

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