RFR: 8305406: Add @spec tags in java.base/java.* (part 2) [v2]

[Jonathan Gibbons]

On Wed, 23 Oct 2024 21:14:23 GMT, Valerie Peng <valeriep at openjdk.org> wrote:

> Is "https://tools.ietf.org/html/rfc8103" considered external spec? It is mentioned in com.sun.crypto.provider.ChaCha20Poly1305Parameters class but not covered in this PR. Is there any additional condition for an external reference to be included? How about an external reference to a section of a specification? E.g. http://www.w3.org/TR/xmlenc-core/#sec-Alg-SymmetricKeyWrap in com.sun.crypto.provider.DESedeWrapCipher class which is also not covered by this PR.

Valerie,

The intent of `@spec` is to include any external specification that is referenced in the public API documentation. As a rule of thumb, an external specification is any one given by name and/or an absolute URL. Note, not all references with absolute URLs are specifications. Some may be references to additional non-normative sources such as guides and similar materials.

This PR, and others that have preceded it, are mechanically derived by examining `@see` and `{@link}` tags in public API documentation. Once this initial work has been completed, it will be up to individual component teams to update any `@spec` tags in their area, either adding new tags, or modifying/updating the URLs of existing tags.

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

PR Comment: https://git.openjdk.org/jdk/pull/21326#issuecomment-2433543714