[clang-tools-extra] 2706919 - [clang-tidy][doc] Improve clang-tidy documentation
Carlos Galvez via cfe-commits
cfe-commits at lists.llvm.org
Thu Feb 9 04:20:51 PST 2023
Author: Carlos Galvez
Date: 2023-02-09T12:19:36Z
New Revision: 2706919f91977f3859ad625d4fb624fb04857e4f
URL: https://github.com/llvm/llvm-project/commit/2706919f91977f3859ad625d4fb624fb04857e4f
DIFF: https://github.com/llvm/llvm-project/commit/2706919f91977f3859ad625d4fb624fb04857e4f.diff
LOG: [clang-tidy][doc] Improve clang-tidy documentation
- Specify that the .clang-tidy file is in YAML format.
- Document the options that may be used in the .clang-tidy file,
- Add missing documentation for existing options (User).
- Fix spurious newline after the dash that comes after every
command-line option. This was inconsistent with single-line
descriptions, which lacked a newline. The description is now
aligned with the dash and the corresponding command-line option,
more visually pleasing.
This enables documenting upcoming global clang-tidy
configuration options.
Differential Revision: https://reviews.llvm.org/D141144
Added:
Modified:
clang-tools-extra/clang-tidy/tool/ClangTidyMain.cpp
clang-tools-extra/docs/clang-tidy/index.rst
Removed:
################################################################################
diff --git a/clang-tools-extra/clang-tidy/tool/ClangTidyMain.cpp b/clang-tools-extra/clang-tidy/tool/ClangTidyMain.cpp
index 765b8483561ea..ff673e78a2836 100644
--- a/clang-tools-extra/clang-tidy/tool/ClangTidyMain.cpp
+++ b/clang-tools-extra/clang-tidy/tool/ClangTidyMain.cpp
@@ -31,6 +31,10 @@
using namespace clang::tooling;
using namespace llvm;
+static cl::desc desc(StringRef description) {
+ return cl::desc(description.ltrim());
+}
+
static cl::OptionCategory ClangTidyCategory("clang-tidy options");
static cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage);
@@ -38,13 +42,37 @@ static cl::extrahelp ClangTidyHelp(R"(
Configuration files:
clang-tidy attempts to read configuration for each source file from a
.clang-tidy file located in the closest parent directory of the source
- file. If InheritParentConfig is true in a config file, the configuration file
- in the parent directory (if any exists) will be taken and current config file
- will be applied on top of the parent one. If any configuration options have
- a corresponding command-line option, command-line option takes precedence.
- The effective configuration can be inspected using -dump-config:
-
- $ clang-tidy -dump-config
+ file. The .clang-tidy file is specified in YAML format. If any configuration
+ options have a corresponding command-line option, command-line option takes
+ precedence.
+
+ The following configuration options may be used in a .clang-tidy file:
+
+ CheckOptions - List of key-value pairs defining check-specific
+ options. Example:
+ CheckOptions:
+ some-check.SomeOption: 'some value'
+ Checks - Same as '--checks'.
+ ExtraArgs - Same as '--extra-args'.
+ ExtraArgsBefore - Same as '--extra-args-before'.
+ FormatStyle - Same as '--format-style'.
+ HeaderFilterRegex - Same as '--header-filter-regex'.
+ InheritParentConfig - If this option is true in a config file, the
+ configuration file in the parent directory
+ (if any exists) will be taken and the current
+ config file will be applied on top of the
+ parent one.
+ SystemHeaders - Same as '--system-headers'.
+ UseColor - Same as '--use-color'.
+ User - Specifies the name or e-mail of the user
+ running clang-tidy. This option is used, for
+ example, to place the correct user name in
+ TODO() comments in the relevant check.
+ WarningsAsErrors - Same as '--warnings-as-errors'.
+
+ The effective configuration can be inspected using --dump-config:
+
+ $ clang-tidy --dump-config
---
Checks: '-*,some-check'
WarningsAsErrors: ''
@@ -62,7 +90,7 @@ const char DefaultChecks[] = // Enable these checks by default:
"clang-diagnostic-*," // * compiler diagnostics
"clang-analyzer-*"; // * Static Analyzer checks
-static cl::opt<std::string> Checks("checks", cl::desc(R"(
+static cl::opt<std::string> Checks("checks", desc(R"(
Comma-separated list of globs with optional '-'
prefix. Globs are processed in order of
appearance in the list. Globs without '-'
@@ -75,7 +103,7 @@ file, if any.
)"),
cl::init(""), cl::cat(ClangTidyCategory));
-static cl::opt<std::string> WarningsAsErrors("warnings-as-errors", cl::desc(R"(
+static cl::opt<std::string> WarningsAsErrors("warnings-as-errors", desc(R"(
Upgrades warnings to errors. Same format as
'-checks'.
This option's value is appended to the value of
@@ -85,7 +113,7 @@ file, if any.
cl::init(""),
cl::cat(ClangTidyCategory));
-static cl::opt<std::string> HeaderFilter("header-filter", cl::desc(R"(
+static cl::opt<std::string> HeaderFilter("header-filter", desc(R"(
Regular expression matching the names of the
headers to output diagnostics from. Diagnostics
from the main file of each translation unit are
@@ -99,9 +127,9 @@ option in .clang-tidy file, if any.
static cl::opt<bool>
SystemHeaders("system-headers",
- cl::desc("Display the errors from system headers."),
+ desc("Display the errors from system headers."),
cl::init(false), cl::cat(ClangTidyCategory));
-static cl::opt<std::string> LineFilter("line-filter", cl::desc(R"(
+static cl::opt<std::string> LineFilter("line-filter", desc(R"(
List of files with line ranges to filter the
warnings. Can be used together with
-header-filter. The format of the list is a
@@ -114,14 +142,14 @@ JSON array of objects:
cl::init(""),
cl::cat(ClangTidyCategory));
-static cl::opt<bool> Fix("fix", cl::desc(R"(
+static cl::opt<bool> Fix("fix", desc(R"(
Apply suggested fixes. Without -fix-errors
clang-tidy will bail out if any compilation
errors were found.
)"),
cl::init(false), cl::cat(ClangTidyCategory));
-static cl::opt<bool> FixErrors("fix-errors", cl::desc(R"(
+static cl::opt<bool> FixErrors("fix-errors", desc(R"(
Apply suggested fixes even if compilation
errors were found. If compiler errors have
attached fix-its, clang-tidy will apply them as
@@ -129,16 +157,16 @@ well.
)"),
cl::init(false), cl::cat(ClangTidyCategory));
-static cl::opt<bool> FixNotes("fix-notes", cl::desc(R"(
-If a warning has no fix, but a single fix can
-be found through an associated diagnostic note,
-apply the fix.
-Specifying this flag will implicitly enable the
+static cl::opt<bool> FixNotes("fix-notes", desc(R"(
+If a warning has no fix, but a single fix can
+be found through an associated diagnostic note,
+apply the fix.
+Specifying this flag will implicitly enable the
'--fix' flag.
)"),
cl::init(false), cl::cat(ClangTidyCategory));
-static cl::opt<std::string> FormatStyle("format-style", cl::desc(R"(
+static cl::opt<std::string> FormatStyle("format-style", desc(R"(
Style for formatting code around applied fixes:
- 'none' (default) turns off formatting
- 'file' (literally 'file', not a placeholder)
@@ -152,23 +180,23 @@ information about formatting styles and options.
This option overrides the 'FormatStyle` option in
.clang-tidy file, if any.
)"),
- cl::init("none"),
- cl::cat(ClangTidyCategory));
+ cl::init("none"),
+ cl::cat(ClangTidyCategory));
-static cl::opt<bool> ListChecks("list-checks", cl::desc(R"(
+static cl::opt<bool> ListChecks("list-checks", desc(R"(
List all enabled checks and exit. Use with
-checks=* to list all available checks.
)"),
cl::init(false), cl::cat(ClangTidyCategory));
-static cl::opt<bool> ExplainConfig("explain-config", cl::desc(R"(
+static cl::opt<bool> ExplainConfig("explain-config", desc(R"(
For each enabled check explains, where it is
enabled, i.e. in clang-tidy binary, command
line or a specific configuration file.
)"),
cl::init(false), cl::cat(ClangTidyCategory));
-static cl::opt<std::string> Config("config", cl::desc(R"(
+static cl::opt<std::string> Config("config", desc(R"(
Specifies a configuration in YAML/JSON format:
-config="{Checks: '*',
CheckOptions: {x: y}}"
@@ -178,7 +206,7 @@ each source file in its parent directories.
)"),
cl::init(""), cl::cat(ClangTidyCategory));
-static cl::opt<std::string> ConfigFile("config-file", cl::desc(R"(
+static cl::opt<std::string> ConfigFile("config-file", desc(R"(
Specify the path of .clang-tidy or custom config file:
e.g. --config-file=/some/path/myTidyConfigFile
This option internally works exactly the same way as
@@ -188,7 +216,7 @@ Use either --config-file or --config, not both.
cl::init(""),
cl::cat(ClangTidyCategory));
-static cl::opt<bool> DumpConfig("dump-config", cl::desc(R"(
+static cl::opt<bool> DumpConfig("dump-config", desc(R"(
Dumps configuration in the YAML format to
stdout. This option can be used along with a
file name (and '--' if the file is outside of a
@@ -200,15 +228,14 @@ configuration of all checks.
)"),
cl::init(false), cl::cat(ClangTidyCategory));
-static cl::opt<bool> EnableCheckProfile("enable-check-profile", cl::desc(R"(
+static cl::opt<bool> EnableCheckProfile("enable-check-profile", desc(R"(
Enable per-check timing profiles, and print a
report to stderr.
)"),
cl::init(false),
cl::cat(ClangTidyCategory));
-static cl::opt<std::string> StoreCheckProfile("store-check-profile",
- cl::desc(R"(
+static cl::opt<std::string> StoreCheckProfile("store-check-profile", desc(R"(
By default reports are printed in tabulated
format to stderr. When this option is passed,
these per-TU profiles are instead stored as JSON.
@@ -224,7 +251,7 @@ static cl::opt<bool>
cl::init(false), cl::Hidden,
cl::cat(ClangTidyCategory));
-static cl::opt<std::string> ExportFixes("export-fixes", cl::desc(R"(
+static cl::opt<std::string> ExportFixes("export-fixes", desc(R"(
YAML file to store suggested fixes in. The
stored fixes can be applied to the input source
code with clang-apply-replacements.
@@ -232,23 +259,22 @@ code with clang-apply-replacements.
cl::value_desc("filename"),
cl::cat(ClangTidyCategory));
-static cl::opt<bool> Quiet("quiet", cl::desc(R"(
+static cl::opt<bool> Quiet("quiet", desc(R"(
Run clang-tidy in quiet mode. This suppresses
printing statistics about ignored warnings and
warnings treated as errors if the respective
options are specified.
)"),
- cl::init(false),
- cl::cat(ClangTidyCategory));
+ cl::init(false), cl::cat(ClangTidyCategory));
-static cl::opt<std::string> VfsOverlay("vfsoverlay", cl::desc(R"(
+static cl::opt<std::string> VfsOverlay("vfsoverlay", desc(R"(
Overlay the virtual filesystem described by file
over the real file system.
)"),
cl::value_desc("filename"),
cl::cat(ClangTidyCategory));
-static cl::opt<bool> UseColor("use-color", cl::desc(R"(
+static cl::opt<bool> UseColor("use-color", desc(R"(
Use colors in diagnostics. If not set, colors
will be used if the terminal connected to
standard output supports colors.
@@ -257,7 +283,7 @@ This option overrides the 'UseColor' option in
)"),
cl::init(false), cl::cat(ClangTidyCategory));
-static cl::opt<bool> VerifyConfig("verify-config", cl::desc(R"(
+static cl::opt<bool> VerifyConfig("verify-config", desc(R"(
Check the config files to ensure each check and
option is recognized.
)"),
diff --git a/clang-tools-extra/docs/clang-tidy/index.rst b/clang-tools-extra/docs/clang-tidy/index.rst
index e2a9f95d0e115..1db828ab32d1c 100644
--- a/clang-tools-extra/docs/clang-tidy/index.rst
+++ b/clang-tools-extra/docs/clang-tidy/index.rst
@@ -122,8 +122,7 @@ An overview of all the command-line options:
clang-tidy options:
- --checks=<string> -
- Comma-separated list of globs with optional '-'
+ --checks=<string> - Comma-separated list of globs with optional '-'
prefix. Globs are processed in order of
appearance in the list. Globs without '-'
prefix add checks with matching names to the
@@ -132,21 +131,18 @@ An overview of all the command-line options:
checks. This option's value is appended to the
value of the 'Checks' option in .clang-tidy
file, if any.
- --config=<string> -
- Specifies a configuration in YAML/JSON format:
+ --config=<string> - Specifies a configuration in YAML/JSON format:
-config="{Checks: '*',
- CheckOptions: {x, y}}"
+ CheckOptions: {x: y}}"
When the value is empty, clang-tidy will
attempt to find a file named .clang-tidy for
each source file in its parent directories.
- --config-file=<string> -
- Specify the path of .clang-tidy or custom config file:
- e.g. --config-file=/some/path/myTidyConfigFile
- This option internally works exactly the same way as
+ --config-file=<string> - Specify the path of .clang-tidy or custom config file:
+ e.g. --config-file=/some/path/myTidyConfigFile
+ This option internally works exactly the same way as
--config option after reading specified config file.
- Use either --config-file or --config, not both.
- --dump-config -
- Dumps configuration in the YAML format to
+ Use either --config-file or --config, not both.
+ --dump-config - Dumps configuration in the YAML format to
stdout. This option can be used along with a
file name (and '--' if the file is outside of a
project with configured compilation database).
@@ -154,38 +150,29 @@ An overview of all the command-line options:
printed.
Use along with -checks=* to include
configuration of all checks.
- --enable-check-profile -
- Enable per-check timing profiles, and print a
+ --enable-check-profile - Enable per-check timing profiles, and print a
report to stderr.
- --explain-config -
- For each enabled check explains, where it is
+ --explain-config - For each enabled check explains, where it is
enabled, i.e. in clang-tidy binary, command
line or a specific configuration file.
- --export-fixes=<filename> -
- YAML file to store suggested fixes in. The
+ --export-fixes=<filename> - YAML file to store suggested fixes in. The
stored fixes can be applied to the input source
code with clang-apply-replacements.
- --extra-arg=<string> - Additional argument to append to the compiler command line.
- Can be used several times.
- --extra-arg-before=<string> - Additional argument to prepend to the compiler command line.
- Can be used several times.
- --fix -
- Apply suggested fixes. Without -fix-errors
+ --extra-arg=<string> - Additional argument to append to the compiler command line
+ --extra-arg-before=<string> - Additional argument to prepend to the compiler command line
+ --fix - Apply suggested fixes. Without -fix-errors
clang-tidy will bail out if any compilation
errors were found.
- --fix-errors -
- Apply suggested fixes even if compilation
+ --fix-errors - Apply suggested fixes even if compilation
errors were found. If compiler errors have
attached fix-its, clang-tidy will apply them as
well.
- --fix-notes -
- If a warning has no fix, but a single fix can
+ --fix-notes - If a warning has no fix, but a single fix can
be found through an associated diagnostic note,
apply the fix.
Specifying this flag will implicitly enable the
'--fix' flag.
- --format-style=<string> -
- Style for formatting code around applied fixes:
+ --format-style=<string> - Style for formatting code around applied fixes:
- 'none' (default) turns off formatting
- 'file' (literally 'file', not a placeholder)
uses .clang-format file in the closest parent
@@ -197,16 +184,14 @@ An overview of all the command-line options:
information about formatting styles and options.
This option overrides the 'FormatStyle` option in
.clang-tidy file, if any.
- --header-filter=<string> -
- Regular expression matching the names of the
+ --header-filter=<string> - Regular expression matching the names of the
headers to output diagnostics from. Diagnostics
from the main file of each translation unit are
always displayed.
Can be used together with -line-filter.
This option overrides the 'HeaderFilterRegex'
option in .clang-tidy file, if any.
- --line-filter=<string> -
- List of files with line ranges to filter the
+ --line-filter=<string> - List of files with line ranges to filter the
warnings. Can be used together with
-header-filter. The format of the list is a
JSON array of objects:
@@ -214,43 +199,28 @@ An overview of all the command-line options:
{"name":"file1.cpp","lines":[[1,3],[5,7]]},
{"name":"file2.h"}
]
- --list-checks -
- List all enabled checks and exit. Use with
+ --list-checks - List all enabled checks and exit. Use with
-checks=* to list all available checks.
- -load=<plugin> -
- Load the dynamic object ``plugin``. This
- object should register new static analyzer
- or clang-tidy passes. Once loaded, the
- object will add new command line options
- to run various analyses. To see the new
- complete list of passes, use the
- :option:`--list-checks` and
- :option:`-load` options together.
+ --load=<pluginfilename> - Load the specified plugin
-p <string> - Build path
- --quiet -
- Run clang-tidy in quiet mode. This suppresses
+ --quiet - Run clang-tidy in quiet mode. This suppresses
printing statistics about ignored warnings and
warnings treated as errors if the respective
options are specified.
- --store-check-profile=<prefix> -
- By default reports are printed in tabulated
+ --store-check-profile=<prefix> - By default reports are printed in tabulated
format to stderr. When this option is passed,
these per-TU profiles are instead stored as JSON.
--system-headers - Display the errors from system headers.
- --use-color -
- Use colors in diagnostics. If not set, colors
- will be used if the terminal connected to
- standard output supports colors.
- This option overrides the 'UseColor' option in
- .clang-tidy file, if any.
- --verify-config -
- Check the config files to ensure each check and
+ --use-color - Use colors in diagnostics. If not set, colors
+ will be used if the terminal connected to
+ standard output supports colors.
+ This option overrides the 'UseColor' option in
+ .clang-tidy file, if any.
+ --verify-config - Check the config files to ensure each check and
option is recognized.
- --vfsoverlay=<filename> -
- Overlay the virtual filesystem described by file
+ --vfsoverlay=<filename> - Overlay the virtual filesystem described by file
over the real file system.
- --warnings-as-errors=<string> -
- Upgrades warnings to errors. Same format as
+ --warnings-as-errors=<string> - Upgrades warnings to errors. Same format as
'-checks'.
This option's value is appended to the value of
the 'WarningsAsErrors' option in .clang-tidy
@@ -258,34 +228,58 @@ An overview of all the command-line options:
-p <build-path> is used to read a compile command database.
- For example, it can be a CMake build directory in which a file named
- compile_commands.json exists (use -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
- CMake option to get this output). When no build path is specified,
- a search for compile_commands.json will be attempted through all
- parent paths of the first input file . See:
- https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html for an
- example of setting up Clang Tooling on a source tree.
+ For example, it can be a CMake build directory in which a file named
+ compile_commands.json exists (use -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+ CMake option to get this output). When no build path is specified,
+ a search for compile_commands.json will be attempted through all
+ parent paths of the first input file . See:
+ https://clang.llvm.org/docs/HowToSetupToolingForLLVM.html for an
+ example of setting up Clang Tooling on a source tree.
<source0> ... specify the paths of source files. These paths are
- looked up in the compile command database. If the path of a file is
- absolute, it needs to point into CMake's source tree. If the path is
- relative, the current working directory needs to be in the CMake
- source tree and the file must be in a subdirectory of the current
- working directory. "./" prefixes in the relative files will be
- automatically removed, but the rest of a relative path must be a
- suffix of a path in the compile command database.
+ looked up in the compile command database. If the path of a file is
+ absolute, it needs to point into CMake's source tree. If the path is
+ relative, the current working directory needs to be in the CMake
+ source tree and the file must be in a subdirectory of the current
+ working directory. "./" prefixes in the relative files will be
+ automatically removed, but the rest of a relative path must be a
+ suffix of a path in the compile command database.
Configuration files:
clang-tidy attempts to read configuration for each source file from a
.clang-tidy file located in the closest parent directory of the source
- file. If InheritParentConfig is true in a config file, the configuration file
- in the parent directory (if any exists) will be taken and current config file
- will be applied on top of the parent one. If any configuration options have
- a corresponding command-line option, command-line option takes precedence.
- The effective configuration can be inspected using -dump-config:
-
- $ clang-tidy -dump-config
+ file. The .clang-tidy file is specified in YAML format. If any configuration
+ options have a corresponding command-line option, command-line option takes
+ precedence.
+
+ The following configuration options may be used in a .clang-tidy file:
+
+ CheckOptions - List of key-value pairs defining check-specific
+ options. Example:
+ CheckOptions:
+ some-check.SomeOption: 'some value'
+ Checks - Same as '--checks'.
+ ExtraArgs - Same as '--extra-args'.
+ ExtraArgsBefore - Same as '--extra-args-before'.
+ FormatStyle - Same as '--format-style'.
+ HeaderFilterRegex - Same as '--header-filter-regex'.
+ InheritParentConfig - If this option is true in a config file, the
+ configuration file in the parent directory
+ (if any exists) will be taken and the current
+ config file will be applied on top of the
+ parent one.
+ SystemHeaders - Same as '--system-headers'.
+ UseColor - Same as '--use-color'.
+ User - Specifies the name or e-mail of the user
+ running clang-tidy. This option is used, for
+ example, to place the correct user name in
+ TODO() comments in the relevant check.
+ WarningsAsErrors - Same as '--warnings-as-errors'.
+
+ The effective configuration can be inspected using --dump-config:
+
+ $ clang-tidy --dump-config
---
Checks: '-*,some-check'
WarningsAsErrors: ''
More information about the cfe-commits
mailing list