I've recently discovered some issues with @jls and @jvms tags. I'll describe the issues first and then propose a tentative solution.

# Issues

## Bitrot

Even if initially correct, subsequent changes to the respective specifications can make individual tags incorrect. This can be easily seen with the block variant of the tags because that variant takes a specification section heading as an argument which you can compare with the actual specification heading by following the generated link.

One example is rearranging sections. In JLS 14, a portion of the TOC looks like this:

    3.10.6. Escape Sequences for Character and String Literals
    3.10.7. The Null Literal
    3.11. Separators

So, the following @jls tag is correct:

     * @jls 3.10.7 The Null Literal
     ...
    public interface NullType extends ReferenceType {

However, in JLS 15, that portion of the TOC looks like this, making the above tag incorrect:

    3.10.7. Escape Sequences
    3.10.8. The Null Literal
    3.11. Separators

That tag has not been fixed since.

Another example, which perhaps is less severe, is rewording a section. In JLS (First Edition, 1996) the section 6.7 looks like this:

    6.7 Fully Qualified Names

However, in JLS (Second Edition, 2000) that same section looks like this:

    6.7 Fully Qualified Names and Canonical Names

Meanwhile, this tag in `Class` looks like this:

     * @jls 6.7 Fully Qualified Names
     */
    public String getPackageName() {

## Broken Links

If the section number in a tag ends up with a trailing period, the generated link will be broken. This is at odds with the specifications, where sections have trailing periods. So, if the author populates the tag from the specification, deleting the trailing period is required for the link to work.

For example, the specification has this:

    9.1.1. Interface Modifiers

And the following tag generates a broken link:

     * @jls 9.1.1. Interface Modifiers

If the tag were like this instead, the link would be correct:

     * @jls 9.1.1 Interface Modifiers

In general, anything can be put into a tag as long as the format is correct. The link will be created, but if the tag contents do not correspond to anything in TOC, this link will be broken.

# Solution

Relying on occasional proofreading is bad. If it is actually done, which I doubt, it clearly does not catch all the issues. Creating a side script that is occasionally run is better but not ideal. I've heard there was such a script somewhere. I reckon it either hasn't been run for a long time or does a bad job catching issues.

A better solution is to modify the tags themselves to performs checks. That way the checks will be performed every time the documentation is made, which happens very often because these days the documentation is made in CI pipelines. Powerful diagnostic reporting comes as a bonus: any issues will be paired with their precise locations.

One problem is that CI environments are unlikely to have access to the Internet. This means that he TOC should be available as an easily upgradable offline file checked in into the repo. The tags could then initially check if the file corresponds to the version of JDK being built. If it doesn't, the tags could issue a warning and maybe provide a hint on how to update the file. This file should be upgraded every six months (i.e. per JDK release).

A few details:

- Trailing period in a section should be optional. This will repair some links and facilitate copy-paste from TOC.

- Some typographical differences between the tag heading and that of the specification could be ignored for checks.

   For example, this:

        14.15. The <code class="literal">break</code> Statement

   Could be considered to be the same as this:

        @jls 14.15. The code break Statement

   As well as this:

        @jls 14.15. The code {@code break} Statement

- While bitrot can be easily seen with the block variant of the tags, it does not mean bitrot does not affect inline variants. The proposal is to allow inline variants to have an argument of the same semantics as that of the block variant. To ease migration, that argument could be made optional, at least initially.