Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8274926

No way to locally suppress doclint warnings

XMLWordPrintable

    • Icon: CSR CSR
    • Resolution: Approved
    • Icon: P3 P3
    • 18
    • tools
    • None
    • behavioral
    • minimal
    • new feature, using a previously unused argument for `@SuppressWarnings`
    • Java API

      Summary

      Leverage the @SuppressWarnings mechanism to suppress warnings generated by DocLint.

      Problem

      javac and javadoc provide support for checking the content of documentation comments. Some limited capability is provided by command-line options to control which checks are enabled, but in conjunction with other options, these options apply to all comments being checked, with no way to disable warnings in specific documentation comments.

      Solution

      The standard way to suppress warnings in javac is by using the @SuppressWarnings mechanism, defined in JLS 9.6.4.5. The annotation does not define the set of strings that may be recognized, with the implication that additional strings may be added and recognized over time.

      DocLint is enhanced to recognize new strings, pertaining to the warnings and errors that may be reported regarding issues in documentation comments.

      Specification

      DocLint checks for and recognizes two strings that may be present in the arguments for an @SuppressWarnings annotation.

      • doclint
      • doclint:LIST
        where LIST is a comma-separated list of one or more of
        accessibility, html, missing, syntax, reference.

      The names in LIST are the same "group" names supported by the command-line -Xdoclint option for javac and javadoc. Note: This is the same convention honored by the javac -Xlint option and the corresponding names supported by @SuppressWarnings.

      When DocLint detects an issue in a documentation comment, it checks for the presence of @SuppressWarnings on the associated declaration and on all lexically enclosing declarations. The issue will be ignored if any annotation is found containing the simple string "doclint" or the longer form "doclint:LIST" where LIST contains the name of the group for the issue.

      DocLint may report errors as well as warnings. All messages related to an issue are suppressed by the presence of an appropriate @SuppressWarnings annotation: this includes errors as well as warnings.

      Note: It is only possible to suppress messages. If an annotation of @SuppressWarnings("doclint") is given on a top-level declaration, all DocLint messages for that declaration and any enclosed declarations will be suppressed; it is not possible to selectively re-enable messages for issues in enclosed declarations.

            jjg Jonathan Gibbons
            briangoetz Brian Goetz
            Hannes Wallnoefer, Pavel Rappo (Inactive)
            Votes:
            0 Vote for this issue
            Watchers:
            4 Start watching this issue

              Created:
              Updated:
              Resolved: