RFR: JDK-8296546: Add @spec tags to API

[Jonathan Gibbons]

On Thu, 10 Nov 2022 12:01:11 GMT, Alan Bateman <alanb at openjdk.org> wrote:

> I'm trying to understand what "fix-ups" will be needed if the automated patch is applied. In some cases, it looks the same spec will be linked from "See also" and "External Specifications", e.g. http://cr.openjdk.java.net/~jjg/8296546/api.00/java.base/java/net/StandardSocketOptions.html#TCP_NODELAY so the `@see` ref can be dropped.
> 
> In other cases we will have inline refs and the same URL in the `@spec`. This may be okay for the short term but maybe there is a way to inline `@spec` to avoid the duplication?
> 
> There will probably be a bit of cleanup to reflow some lines, e.g. StandardSocketOptions.java, as excessively long lines are problematic for side-by-side diffs.

The utility I mentioned has the (optional) ability to remove `@see` links when the text of the link exactly matches that used by the `@spec` tag.  Unfortunately, the text is typically not exactly the same, and would require manual analysis to see if the `@see` tag can be removed.

When inline references are used, the wording is very rarely the primary title of the spec: it is more likely to be a word or phrase that makes sense in the context of the enclosing sentence.

_History: version 1 of this feature tried replacing inline links and `@see` tags with a bi-modal `@spec` tag. The results were "not good", especially in the generated external-specs page.  Version 2 used a side file to provide the definitive title for each spec, but that was deemed to be too much of a maintenance issue. This is version 3, in which we've eliminated the side-file in favor of duplicating the title in each `@spec` tag._

-------------

PR: https://git.openjdk.org/jdk/pull/11073