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

[Bradford Wetmore]

On Wed, 5 Apr 2023 16:45:06 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a doc update to add `@spec` into the rest of the files in `java.base` (compared to those in [JDK-8305206](https://bugs.openjdk.org/browse/JDK-8305206) PR #13248)
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Address review feedback

I'm coming to this late, but what is the breadth of the specs you're trying to call out?  Where did you obtain this list?  Are all of these changes coming from existing mentions in the current APIs, and you're just adding a `@spec` in various places?   Or are you trying to be complete, or just list a representative sample?   In part 1, I saw you moved some of the spec mentions to be in a `@spec`, but in this PR, you're adding specs in the APIs.

In many of our APIs, we mention things "...such as...RFC 2246...", but we make no effort to be complete by providing a list of specs.

For example:

SSLEngine.java:  only TLSv1.0 was mentioned, but there's also SSLv3/1.1/1.2/1.3, and DTLS 1.0/1.2.

SSLSocket.java:  your change only lists 7301, but not 2246.  But same issue as SSLEngine, there are others specs this also applies to.

java.security.Key.java:  RFC 5280 was the only spec called out.  There are many other Key types.

SecureRandom:  RFC 4086 was called out.  There are others.

If you want to mention a bunch of the security specs, I think we need to better understand the scope of what you're trying to do, and how this will be kept in sync with Chapter 4 of the Security Documentation (Providers):  which also could use some updates-e.g. TLSv1.x RFCs, but that is another RFE for another day.

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

PR Comment: https://git.openjdk.org/jdk/pull/13336#issuecomment-1507930025