RFR: 8230623: Extract command-line help for -Xlint sub-options to new --help-lint [v2]

[Guoxiong Li]

On Wed, 28 Apr 2021 13:01:19 GMT, Joel Borggrén-Franck <jfranck at openjdk.org> wrote:

>> The CSR was created. Please see [JDK-8265772](https://bugs.openjdk.java.net/browse/JDK-8265772).  And I updated the copyright. Thank you for taking the time to review the CSR and this patch.
>
> @lgxbslgx I added myself as a reviewer of the CSR. `javac -X` does not output any lint options on my machine, can you update the CSR it clarifying when `-X` would or would not output lint options,  and/or remove the non-relevant occurrences of `(-X)` ?

@jbf  By using the current master branch code, the command `javac -X` would output the following message.


  --add-exports <module>/<package>=<other-module>(,<other-module>)*
        Specify a package to be considered as exported from its defining module
        to additional modules, or to all unnamed modules if <other-module> is ALL-UNNAMED.
  --add-reads <module>=<other-module>(,<other-module>)*
        Specify additional modules to be considered as required by a given module.
        <other-module> may be ALL-UNNAMED to require the unnamed module.
  --default-module-for-created-files <module-name>
        Fallback target module for files created by annotation processors, if none specified or inferred.
  -Djava.endorsed.dirs=<dirs>  Override location of endorsed standards path
  -Djava.ext.dirs=<dirs>       Override location of installed extensions
  --patch-module <module>=<file>(:<file>)*
        Override or augment a module with classes and resources
        in JAR files or directories
  -Xbootclasspath:<path>       Override location of bootstrap class files
  -Xbootclasspath/a:<path>     Append to the bootstrap class path
  -Xbootclasspath/p:<path>     Prepend to the bootstrap class path
  -Xdiags:{compact,verbose}    Select a diagnostic mode
  -Xdoclint
        Enable recommended checks for problems in javadoc comments
  -Xdoclint:(all|none|[-]<group>)[/<access>]
        Enable or disable specific checks for problems in javadoc comments,
        where <group> is one of accessibility, html, missing, reference, or syntax,
        and <access> is one of public, protected, package, or private.
  -Xdoclint/package:[-]<packages>(,[-]<package>)*
        Enable or disable checks in specific packages. Each <package> is either the
        qualified name of a package or a package name prefix followed by .*, which
        expands to all sub-packages of the given package. Each <package> can be prefixed
        with - to disable checks for the specified package or packages.
  -Xlint                       Enable recommended warnings
  -Xlint:<key>(,<key>)*
        Warnings to enable or disable, separated by comma.
        Precede a key by - to disable the specified warning.
        Supported keys are:
          all                  Enable all warnings
          auxiliaryclass       Warn about an auxiliary class that is hidden in a source file, and is used from other files.
          cast                 Warn about use of unnecessary casts.
          classfile            Warn about issues related to classfile contents.
          deprecation          Warn about use of deprecated items.
          dep-ann              Warn about items marked as deprecated in JavaDoc but not using the @Deprecated annotation.
          divzero              Warn about division by constant integer 0.
          empty                Warn about empty statement after if.
          exports              Warn about issues regarding module exports.
          fallthrough          Warn about falling through from one case of a switch statement to the next.
          finally              Warn about finally clauses that do not terminate normally.
          missing-explicit-ctor Warn about missing explicit constructors in public and protected classes in exported packages.
          module               Warn about module system related issues.
          opens                Warn about issues regarding module opens.
          options              Warn about issues relating to use of command line options.
          overloads            Warn about issues regarding method overloads.
          overrides            Warn about issues regarding method overrides.
          path                 Warn about invalid path elements on the command line.
          processing           Warn about issues regarding annotation processing.
          rawtypes             Warn about use of raw types.
          removal              Warn about use of API that has been marked for removal.
          requires-automatic   Warn about use of automatic modules in the requires clauses.
          requires-transitive-automatic Warn about automatic modules in requires transitive.
          serial               Warn about Serializable classes that do not provide a serial version ID. 
                             Also warn about access to non-public members from a serializable element.
          static               Warn about accessing a static member using an instance.
          synchronization      Warn about synchronization attempts on instances of value-based classes.
          text-blocks          Warn about inconsistent white space characters in text block indentation.
          try                  Warn about issues relating to use of try blocks (i.e. try-with-resources).
          unchecked            Warn about unchecked operations.
          varargs              Warn about potentially unsafe vararg methods.
          preview              Warn about use of preview language features.
          none                 Disable all warnings
  -Xmaxerrs <number>           Set the maximum number of errors to print
  -Xmaxwarns <number>          Set the maximum number of warnings to print
  -Xpkginfo:{always,legacy,nonempty}
        Specify handling of package-info files
  -Xplugin:"name args"
        Name and optional arguments for a plug-in to be run
  -Xprefer:{source,newer}
        Specify which file to read when both a source file and class file are found for an implicitly compiled class
  -Xprint
        Print out a textual representation of specified types
  -XprintProcessorInfo
        Print information about which annotations a processor is asked to process
  -XprintRounds
        Print information about rounds of annotation processing
  -Xstdout <filename>          Redirect standard output

These extra options are subject to change without notice.


Did your machine output the same message? Especially the following output:


  -Xlint                       Enable recommended warnings
  -Xlint:<key>(,<key>)*
        Warnings to enable or disable, separated by comma.
        Precede a key by - to disable the specified warning.
        Supported keys are:    <-------------------- Note here
          all                  Enable all warnings    <-------------------------------- Note here
          auxiliaryclass       Warn about an auxiliary class that is hidden in a source file, and is used from other files.<------Note here
          cast                 Warn about use of unnecessary casts.       <------------------------- Note here
          // <-------------- ignore many other sub-options.
  -Xmaxerrs <number>           Set the maximum number of errors to print


By using the code of this patch, the command `javac -X` would output the following message. We can see that the `Supported keys` is removed.


  --add-exports <module>/<package>=<other-module>(,<other-module>)*
        Specify a package to be considered as exported from its defining module
        to additional modules, or to all unnamed modules if <other-module> is ALL-UNNAMED.
  --add-reads <module>=<other-module>(,<other-module>)*
        Specify additional modules to be considered as required by a given module.
        <other-module> may be ALL-UNNAMED to require the unnamed module.
  --default-module-for-created-files <module-name>
        Fallback target module for files created by annotation processors, if none specified or inferred.
  -Djava.endorsed.dirs=<dirs>  Override location of endorsed standards path
  -Djava.ext.dirs=<dirs>       Override location of installed extensions
  --help-lint                  Print the supported keys of option -Xlint
  --patch-module <module>=<file>(:<file>)*
        Override or augment a module with classes and resources
        in JAR files or directories
  -Xbootclasspath:<path>       Override location of bootstrap class files
  -Xbootclasspath/a:<path>     Append to the bootstrap class path
  -Xbootclasspath/p:<path>     Prepend to the bootstrap class path
  -Xdiags:{compact,verbose}    Select a diagnostic mode
  -Xdoclint
        Enable recommended checks for problems in javadoc comments
  -Xdoclint:(all|none|[-]<group>)[/<access>]
        Enable or disable specific checks for problems in javadoc comments,
        where <group> is one of accessibility, html, missing, reference, or syntax,
        and <access> is one of public, protected, package, or private.
  -Xdoclint/package:[-]<packages>(,[-]<package>)*
        Enable or disable checks in specific packages. Each <package> is either the
        qualified name of a package or a package name prefix followed by .*, which
        expands to all sub-packages of the given package. Each <package> can be prefixed
        with - to disable checks for the specified package or packages.
  -Xlint                       Enable recommended warnings
  -Xlint:<key>(,<key>)*
        Warnings to enable or disable, separated by comma.
        Precede a key by - to disable the specified warning.
        Use option --help-lint to see the supported keys.
  -Xmaxerrs <number>           Set the maximum number of errors to print
  -Xmaxwarns <number>          Set the maximum number of warnings to print
  -Xpkginfo:{always,legacy,nonempty}
        Specify handling of package-info files
  -Xplugin:"name args"
        Name and optional arguments for a plug-in to be run
  -Xprefer:{source,newer}
        Specify which file to read when both a source file and class file are found for an implicitly compiled class
  -Xprint
        Print out a textual representation of specified types
  -XprintProcessorInfo
        Print information about which annotations a processor is asked to process
  -XprintRounds
        Print information about rounds of annotation processing
  -Xstdout <filename>          Redirect standard output

These extra options are subject to change without notice.


And the command `javac --help-lint` would output the following message.


The supported keys of option -Xlint are:
    all                  Enable all warnings
    auxiliaryclass       Warn about an auxiliary class that is hidden in a source file, and is used from other files.
    cast                 Warn about use of unnecessary casts.
    classfile            Warn about issues related to classfile contents.
    deprecation          Warn about use of deprecated items.
    dep-ann              Warn about items marked as deprecated in JavaDoc but not using the @Deprecated annotation.
    divzero              Warn about division by constant integer 0.
    empty                Warn about empty statement after if.
    exports              Warn about issues regarding module exports.
    fallthrough          Warn about falling through from one case of a switch statement to the next.
    finally              Warn about finally clauses that do not terminate normally.
    missing-explicit-ctor Warn about missing explicit constructors in public and protected classes in exported packages.
    module               Warn about module system related issues.
    opens                Warn about issues regarding module opens.
    options              Warn about issues relating to use of command line options.
    overloads            Warn about issues regarding method overloads.
    overrides            Warn about issues regarding method overrides.
    path                 Warn about invalid path elements on the command line.
    processing           Warn about issues regarding annotation processing.
    rawtypes             Warn about use of raw types.
    removal              Warn about use of API that has been marked for removal.
    requires-automatic   Warn about use of automatic modules in the requires clauses.
    requires-transitive-automatic Warn about automatic modules in requires transitive.
    serial               Warn about Serializable classes that do not provide a serial version ID. 
                         Also warn about access to non-public members from a serializable element.
    static               Warn about accessing a static member using an instance.
    synchronization      Warn about synchronization attempts on instances of value-based classes.
    text-blocks          Warn about inconsistent white space characters in text block indentation.
    try                  Warn about issues relating to use of try blocks (i.e. try-with-resources).
    unchecked            Warn about unchecked operations.
    varargs              Warn about potentially unsafe vararg methods.
    preview              Warn about use of preview language features.
    none                 Disable all warnings


A difference between the CSR and the output are `sub-options` and `Supported keys`. I think the name `sub-options` is good for compilers developer and the name `Supported keys` is good for users. I revised the CSR to clarify it just now .

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

PR: https://git.openjdk.java.net/jdk/pull/1758