After making some changes to the parser, I noticed that the build got broken due to a new "dangling-doc-comments" warning that was being reported - incorrectly, as it turns out, due to my changes. Yet all of the compiler regression tests were still passing.

That indicates that some aspect of how "dangling-doc-comments" behaves is not being verified by the existing regression suite.

That behavioral aspect is the "retroactive" nature of @SuppressWarnings("dangling-doc-comments"). That is, the warning suppression applies to comments preceding the declaration that the annotation annotates, even though those comments are not within the lexical scope of that declaration.

For example:

     /** Dangling comment X */
    
     /** Proper comment Y */
     @SuppressWarnings("dangling-doc-comments")
     public void method() { }

No warning is issued here because the @SuppressWarnings("dangling-doc-comments") applies retroactively to "Dangling comment X".

This particular behavioral aspect should be included in the test suite.