How to scan all javadocs of the Java standard API for the @since tag?

I want to make a map of Java versions to classes, their methods and enum values that exist in the standard Java API since those versions. For example the standard class String exists since Java 1.0 and the String::strip() method exists since Java 11. Both the class and the method have the @since tag with the appropriate Java version in their javadocs and this is what I want to scan programmatically.

Maybe there is another way, not related to javadoc? For example since Java 9 the compiler supports the -release argument that among other things checks the compatibility of the used APIs with the chosen version of Java release. In case of -release 10 and a code with String::strip() a compilation error is thrown. How does the compiler do it? Does it scan the src.zip for javadocs during every compilation or use a smarter technique?

Solution

Parsing @since might be error-prone because there are some pitfalls:

Especially for methods it is inconsistent; for example String.startsWith(String) has @since 1.0 but String.endsWith(String) has no @since tag
The value might be unexpected for overridden methods, see JDK-8254572
It might be incorrect. The value is not validated in any way so it could happen that it is incorrect, examples for this are: JDK-6372816, JDK-8164057, JDK-8260561

If you as developer just want to know which new API was added, you can have a look at the "New" tab of the documentation, added in Java 17 by JDK-8265055 (this is based on the @since information).

The --release option of javac uses the file lib/ct.sym from the JDK installation which stores information about the public API of previous versions. See the "Implementation" section of JEP 247. There are however some pitfalls with this as well:

The support for older versions is dropped; for example Java 12 and newer does not support Java 6
At the moment it does not include information about unsupported API; most prominently sun.misc.Unsafe

There are however third-party tools which allow you to generate or compare the Java API signatures: