RFR: 8339631: Fix block @jls and @jvms tags [v2]

[Pavel Rappo]

On Fri, 6 Sep 2024 09:16:28 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> This fixes some of the recently discovered [issues] with the block variants of the specification tags. While reviewing, please check the proposed changes against the actual specifications. Since the specifications for JDK 23 are not yet available in the HTML format, you can use the specifications for JDK 22, which are reasonably up-to-date:
>> 
>>   - [JLS]
>>   - [JVMS]
>> 
>> Note that this PR does NOT address any issues with the inline variants of the said tags. Those are harder to check. Even flagging suspicious tags requires a human. If you have some time, consider performing similar checks for inline `@jls` and `@jvms` tags in your area. Thanks.
>> 
>> [issues]: https://bugs.openjdk.org/browse/JDK-8339558
>> [JLS]: https://docs.oracle.com/javase/specs/jls/se22/html/index.html
>> [JVMS]: https://docs.oracle.com/javase/specs/jvms/se22/html/index.html
>
> Pavel Rappo has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Link to 8.1.3 instead of 8.5.1
>   
>   8.5.1 was removed in JDK 16. 8.1.3 seems an appropriate substitution.
>   Alternatively, the link can be deleted altogether.

I understand that a PR might not be the best place for a comment like this. Still, it's highly relevant to the review feedback I've got so far. Also, a PR comment will be seen by more people sooner than a JBS comment. This is by the virtue of being fanned out by the mailing lists.

Some reviewers suggested fixing the typography. I could do it, but I think it will pay us more if we pause and think what the broken typography tells us, which I think is that the design of these tags is not entirely what it should be. 

Currently, these tags are really a specialised form of `@see` and `@linkplain`. The block variant corresponds to `@see` and the inline variant corresponds to `@linkplain`.

Since the tag links to a specific resource, it saves the documentation author keystrokes on typing the link to that resource. Along with the visual consistency of the generated documentation, the author also gets some integrity: the tag links to the same version of the specification as that of the documentation.

Unfortunately, mismatching versions is not the only source of broken integrity. Even if initially the tag is accurate, it may degrade over time by various means. This PR is a good evidence that specification sections can be reordered and that their text can be changed. The problem is not the degradation per se, but that it stays unnoticed indefinitely.

In similar situations, we use external checkers as a post-build documentation test. While it's much better than nothing and is more flexible than changing the tags, failing tests are prone to stay problem-listed indefinitely. Which gets us back to square one.

If like me you think that a broken or irrelevant link is bad, we could make these tags provide more integrity. The tags could check their contents against the actual specification and report an error if the contents are not the same (subject to some typographic and formatting leeway). As for the visual consistency, the tags could also make sure the text they generate is of a particular form by automatically carrying over (some) typography from the specification to the generated documentation.

In my mind, this will require having (an extract from) the specification accessible to the tag. Because build system don't typically have access to the Internet, the specification could be stored in the repo and updated every release, which happens every 6 months.

One problem though is what to do when (not if) a spec is not up-to-date. For example, consider these `@jls` tags in JDK 23:

    package java.lang.runtime;
       ...
     * @jls 5.7.1 Exact Testing Conversions
     * @jls 5.7.2 Unconditionally Exact Testing Conversions
       ...
     * @since 23
     */
    public final class ExactConversionsSupport {

These tags relate to a preview feature, which is documented not in JLS but in an annex to it, which is currently missing due to a build error. If the tags are to strictly check their integrity, a problem like this would prevent a documentation build.

Thoughts?

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

PR Comment: https://git.openjdk.org/jdk/pull/20879#issuecomment-2333914768