[clang-tools-extra] [clang-tidy][docs] Rewrite selected rst docs to md [2/2] (PR #234571)
via cfe-commits
cfe-commits at lists.llvm.org
Fri Nov 13 05:52:32 PST 2026
llvmorg-github-actions[bot] wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-clang-tools-extra
Author: Sachin 🗲 (s4chinjha)
<details>
<summary>Changes</summary>
Tracking issue: [#<!-- -->201242](https://github.com/llvm/llvm-project/issues/201242)
See the [migration guide](https://llvm.org/docs/SphinxQuickstartTemplate.html#markdown-migration-guidelines) for more information.
this is the second part of migrating the selected clang-tidy rst docs to md
the content conversion is provided by this pr, following the rename in the previous pr
this was prepared with rnk's fork of rst2myst and LLM-assisted cleanup.
I manually verified that the documentation renders as expected.
Depends on #<!-- -->234570
the first commit is from the base pr (rename), the second commit contains the content conversion
---
Patch is 177.64 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/234571.diff
16 Files Affected:
- (modified) clang-tools-extra/clang-tidy/doc8.ini (+1-1)
- (modified) clang-tools-extra/docs/clang-tidy.md (+1-1)
- (added) clang-tools-extra/docs/clang-tidy/Contributing.md (+804)
- (removed) clang-tools-extra/docs/clang-tidy/Contributing.rst (-866)
- (added) clang-tools-extra/docs/clang-tidy/ExternalClang-TidyExamples.md (+27)
- (removed) clang-tools-extra/docs/clang-tidy/ExternalClang-TidyExamples.rst (-31)
- (added) clang-tools-extra/docs/clang-tidy/Integrations.md (+100)
- (removed) clang-tools-extra/docs/clang-tidy/Integrations.rst (-123)
- (renamed) clang-tools-extra/docs/clang-tidy/QueryBasedCustomChecks.md (+49-56)
- (added) clang-tools-extra/docs/clang-tidy/checks/llvmlibc/implementation-in-namespace.md (+37)
- (removed) clang-tools-extra/docs/clang-tidy/checks/llvmlibc/implementation-in-namespace.rst (-37)
- (added) clang-tools-extra/docs/clang-tidy/checks/llvmlibc/restrict-system-libc-headers.md (+34)
- (removed) clang-tools-extra/docs/clang-tidy/checks/llvmlibc/restrict-system-libc-headers.rst (-35)
- (added) clang-tools-extra/docs/clang-tidy/index.md (+602)
- (removed) clang-tools-extra/docs/clang-tidy/index.rst (-616)
- (modified) clang-tools-extra/docs/conf.py (+3)
``````````diff
diff --git a/clang-tools-extra/clang-tidy/doc8.ini b/clang-tools-extra/clang-tidy/doc8.ini
index 514e75ad01df5..9b484f8e49edb 100644
--- a/clang-tools-extra/clang-tidy/doc8.ini
+++ b/clang-tools-extra/clang-tidy/doc8.ini
@@ -1,3 +1,3 @@
[doc8]
-ignore-path = clang-tools-extra/docs/clang-tidy/Integrations.rst
+ignore-path = clang-tools-extra/docs/clang-tidy/Integrations.md
ignore = D001
diff --git a/clang-tools-extra/docs/clang-tidy.md b/clang-tools-extra/docs/clang-tidy.md
index 6bc6e2d341ab2..2421760518116 100644
--- a/clang-tools-extra/docs/clang-tidy.md
+++ b/clang-tools-extra/docs/clang-tidy.md
@@ -7,4 +7,4 @@ orphan: true
:http-equiv=refresh: 0;URL='clang-tidy/'
```
-clang-tidy documentation has moved here: [clang-tidy](clang-tidy/index.rst)
+clang-tidy documentation has moved here: [clang-tidy](clang-tidy/index.md)
diff --git a/clang-tools-extra/docs/clang-tidy/Contributing.md b/clang-tools-extra/docs/clang-tidy/Contributing.md
new file mode 100644
index 0000000000000..4ad41cd9715ee
--- /dev/null
+++ b/clang-tools-extra/docs/clang-tidy/Contributing.md
@@ -0,0 +1,804 @@
+# Getting Involved
+
+{program}`clang-tidy` has several own checks and can run Clang Static Analyzer
+checks, but its power is in the ability to easily write custom checks.
+
+Checks are organized in modules, which can be linked into {program}`clang-tidy`
+with minimal or no code changes in {program}`clang-tidy`.
+
+Checks can plug into the analysis on the preprocessor level using
+[PPCallbacks][ppcallbacks] or on the AST level using [AST Matchers][ast matchers]. When an error is
+found, checks can report them in a way similar to how Clang diagnostics work.
+A fix-it hint can be attached to a diagnostic message.
+
+The interface provided by {program}`clang-tidy` makes it easy to write useful
+and precise checks in just a few lines of code. If you have an idea for a good
+check, the rest of this document explains how to do this.
+
+There are a few tools particularly useful when developing Clang-Tidy checks:
+: - `add_new_check.py` is a script to automate the process of adding a new
+ check; it will create the check, update the CMake file and create a test.
+ - `rename_check.py` does what the script name suggests, renames an existing
+ check.
+ - {program}`pp-trace` logs method calls on `PPCallbacks` for a source file
+ and is invaluable in understanding the preprocessor mechanism.
+ - {program}`clang-query` is invaluable for interactive prototyping of AST
+ matchers and exploration of the Clang AST;
+ - [clang-check][clang-check] with the `-ast-dump` (and optionally `-ast-dump-filter`)
+ provides a convenient way to dump AST of a C++ program.
+
+If CMake is configured with `CLANG_TIDY_ENABLE_STATIC_ANALYZER=NO`,
+{program}`clang-tidy` will not be built with support for the
+`clang-analyzer-*` checks or the `mpi-*` checks.
+
+If CMake is configured with `CLANG_TIDY_ENABLE_QUERY_BASED_CUSTOM_CHECKS=NO`,
+{program}`clang-tidy` will not be built with support for query based checks.
+
+## Choosing the Right Place for your Check
+
+If you have an idea of a check, you should decide whether it should be
+implemented as a:
+
+- *Clang diagnostic*: if the check is generic enough, targets code patterns that
+ most probably are bugs (rather than style or readability issues), can be
+ implemented effectively and with extremely low false-positive rate, it may
+ make a good Clang diagnostic.
+- *Clang static analyzer check*: if the check requires some sort of control flow
+ analysis, it should probably be implemented as a static analyzer check.
+- *clang-tidy check* is a good choice for linter-style checks, checks that are
+ related to a certain coding style, checks that address code readability, etc.
+
+## Preparing your Workspace
+
+If you are new to LLVM development, you should read the [Getting Started with
+the LLVM System][getting started with the llvm system], [Using Clang Tools][using clang tools] and [How To Setup Clang Tooling For
+LLVM][how to setup clang tooling for llvm] documents to check out and build LLVM, Clang and Clang Extra Tools with
+CMake.
+
+Once you are done, change to the `llvm/clang-tools-extra` directory, and
+let's start!
+
+When you [configure the CMake build](https://llvm.org/docs/GettingStarted.html#local-llvm-configuration),
+make sure that you enable the `clang` and `clang-tools-extra` projects to
+build {program}`clang-tidy`.
+Because your new check will have associated documentation, you will also want
+to install [Sphinx](https://www.sphinx-doc.org/en/master/) and enable it in
+the CMake configuration. To save build time of the core Clang libraries, you
+may want to only enable the `X86` target in the CMake configuration.
+
+## The Directory Structure
+
+{program}`clang-tidy` source code resides in the
+`llvm/clang-tools-extra` directory and is structured as follows:
+
+```
+clang-tidy/ # Clang-Tidy core.
+|-- ClangTidy.h # Interfaces for users.
+|-- ClangTidyCheck.h # Interfaces for checks.
+|-- ClangTidyModule.h # Interface for Clang-Tidy modules.
+ ...
+|-- google/ # Google Clang-Tidy module.
+|-+
+ |-- GoogleTidyModule.cpp
+ |-- GoogleTidyModule.h
+ ...
+|-- llvm/ # LLVM Clang-Tidy module.
+|-+
+ |-- LLVMTidyModule.cpp
+ |-- LLVMTidyModule.h
+ ...
+|-- objc/ # Objective-C Clang-Tidy module.
+|-+
+ |-- ObjCTidyModule.cpp
+ |-- ObjCTidyModule.h
+ ...
+|-- tool/ # Sources of the Clang-Tidy binary.
+ ...
+test/clang-tidy/ # Integration tests.
+ ...
+unittests/clang-tidy/ # Unit tests.
+|-- ClangTidyTest.h
+|-- GoogleModuleTest.cpp
+|-- LLVMModuleTest.cpp
+ ...
+```
+
+## Writing a Clang-Tidy Check
+
+So you have an idea of a useful check for {program}`clang-tidy`.
+
+First, if you're not familiar with LLVM development, read through the [Getting
+Started with the LLVM System][getting started with the llvm system] document for instructions on setting up your
+workflow and the [LLVM Coding Standards][llvm coding standards] document to familiarize yourself
+with the coding style used in the project. Code reviews for Clang-Tidy
+contributions are done through [LLVM Github][llvm github].
+
+Next, you need to decide which module the check belongs to. Modules
+are located in subdirectories of [clang-tidy/](https://github.com/llvm/llvm-project/tree/main/clang-tools-extra/clang-tidy/)
+and contain checks targeting a certain aspect of code quality (performance,
+readability, etc.), a certain coding style or standard (Google, LLVM, CERT,
+etc.) or a widely used API (e.g. MPI). Their names are the same as the
+user-facing check group names described {ref}`above <checks-groups-table>`.
+
+After choosing the module and the name for the check, run the
+`clang-tidy/add_new_check.py` script to create the skeleton of the check and
+plug it to {program}`clang-tidy`. It's the recommended way of adding new
+checks.
+
+By default, the new check will apply only to C++ code. If it should apply under
+different language options, use the `--language` script's parameter.
+
+If we want to create a `readability-awesome-function-names`, we would run:
+
+```console
+$ clang-tidy/add_new_check.py readability awesome-function-names
+```
+
+The `add_new_check.py` script will:
+: - create the class for your check inside the specified module's directory and
+ register it in the module and in the build system;
+ - create a lit test file in the `test/clang-tidy/` directory;
+ - create a documentation file and include it into the
+ `docs/clang-tidy/checks/list.md`.
+
+Let's look at the check class definition in more detail:
+
+```c++
+...
+
+#include "../ClangTidyCheck.h"
+
+namespace clang::tidy::readability {
+
+...
+class AwesomeFunctionNamesCheck : public ClangTidyCheck {
+public:
+ AwesomeFunctionNamesCheck(StringRef Name, ClangTidyContext *Context)
+ : ClangTidyCheck(Name, Context) {}
+ void registerMatchers(ast_matchers::MatchFinder *Finder) override;
+ void check(const ast_matchers::MatchFinder::MatchResult &Result) override;
+ bool isLanguageVersionSupported(const LangOptions &LangOpts) const override {
+ return LangOpts.CPlusPlus;
+ }
+};
+
+} // namespace clang::tidy::readability
+
+...
+```
+
+Constructor of the check receives the `Name` and `Context` parameters, and
+must forward them to the `ClangTidyCheck` constructor.
+
+In our case the check needs to operate on the AST level and it overrides the
+`registerMatchers` and `check` methods. If we wanted to analyze code on the
+preprocessor level, we'd need instead to override the `registerPPCallbacks`
+method.
+
+In the `registerMatchers` method, we create an AST Matcher (see [AST
+Matchers][ast matchers] for more information) that will find the pattern in the AST that we
+want to inspect. The results of the matching are passed to the `check` method,
+which can further inspect them and report diagnostics.
+
+```c++
+using namespace ast_matchers;
+
+void AwesomeFunctionNamesCheck::registerMatchers(MatchFinder *Finder) {
+ Finder->addMatcher(functionDecl().bind("x"), this);
+}
+
+void AwesomeFunctionNamesCheck::check(const MatchFinder::MatchResult &Result) {
+ const auto *MatchedDecl = Result.Nodes.getNodeAs<FunctionDecl>("x");
+ if (!MatchedDecl->getIdentifier() || MatchedDecl->getName().startswith("awesome_"))
+ return;
+ diag(MatchedDecl->getLocation(), "function %0 is insufficiently awesome")
+ << MatchedDecl
+ << FixItHint::CreateInsertion(MatchedDecl->getLocation(), "awesome_");
+}
+```
+
+(If you want to see an example of a useful check, look at
+[clang-tidy/misc/ExplicitConstructorCheck.h](https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/clang-tidy/misc/ExplicitConstructorCheck.h)
+and [clang-tidy/misc/ExplicitConstructorCheck.cpp](https://github.com/llvm/llvm-project/blob/main/clang-tools-extra/clang-tidy/misc/ExplicitConstructorCheck.cpp)).
+
+If you need to interact with macros or preprocessor directives, you will want
+to override the method `registerPPCallbacks`. The `add_new_check.py`
+script does not generate an override for this method in the starting point for
+your new check.
+
+## Check development tips
+
+Writing your first check can be a daunting task, particularly if you are
+unfamiliar with the LLVM and Clang code bases. Here are some suggestions for
+orienting yourself in the codebase and working on your check incrementally.
+
+### Guide to useful documentation
+
+Many of the support classes created for LLVM are used by Clang, such as [StringRef](https://llvm.org/docs/ProgrammersManual.html#the-stringref-class)
+and [SmallVector](https://llvm.org/docs/ProgrammersManual.html#llvm-adt-smallvector-h).
+These and other commonly used classes are described in the [Important and
+useful LLVM APIs](https://llvm.org/docs/ProgrammersManual.html#important-and-useful-llvm-apis)
+and [Picking the Right Data Structure for the Task](https://llvm.org/docs/ProgrammersManual.html#picking-the-right-data-structure-for-a-task)
+sections of the `LLVM Programmer's Manual
+<https://llvm.org/docs/ProgrammersManual.html>`. You don't need to memorize all the
+details of these classes; the generated [doxygen documentation](https://llvm.org/doxygen/)
+has everything if you need it. In the header [LLVM/ADT/STLExtras.h](https://llvm.org/doxygen/STLExtras_8h.html) you'll find useful versions of the STL
+algorithms that operate on LLVM containers, such as [llvm::all_of](https://llvm.org/doxygen/STLExtras_8h.html#func-members).
+
+Clang is implemented on top of LLVM and introduces its own set of classes that
+you will interact with while writing your check. When a check issues
+diagnostics and fix-its, these are associated with locations in the source
+code. Source code locations, source files, ranges of source locations and the
+[SourceManager](https://clang.llvm.org/doxygen/classclang_1_1SourceManager.html)
+class provide the mechanisms for describing such locations. These and
+other topics are described in the ["Clang" CFE Internals Manual](https://clang.llvm.org/docs/InternalsManual.html). Whereas the doxygen generated
+documentation serves as a reference to the internals of Clang, this document
+serves as a guide to other developers. Topics in that manual of interest to a
+check developer are:
+
+- [The Clang "Basic" Library](https://clang.llvm.org/docs/InternalsManual.html#the-clang-basic-library) for
+ information about diagnostics, fix-it hints and source locations.
+- [The Lexer and Preprocessor Library](https://clang.llvm.org/docs/InternalsManual.html#the-lexer-and-preprocessor-library)
+ for information about tokens, lexing (transforming characters into tokens)
+ and the preprocessor.
+- [The AST Library](https://clang.llvm.org/docs/InternalsManual.html#the-ast-library)
+ for information about how C++ source statements are represented as an
+ abstract syntax tree (AST).
+
+Most checks will interact with C++ source code via the AST. Some checks will
+interact with the preprocessor. The input source file is lexed and preprocessed
+and then parsed into the AST. Once the AST is fully constructed, the check is
+run by applying the check's registered AST matchers against the AST and
+invoking the check with the set of matched nodes from the AST. Monitoring the
+actions of the preprocessor is detached from the AST construction, but a check
+can collect information during preprocessing for later use by the check when
+nodes are matched by the AST.
+
+Every syntactic (and sometimes semantic) element of the C++ source code is
+represented by different classes in the AST. You select the portions of the
+AST you're interested in by composing AST matcher functions. You will want
+to study carefully the [AST Matcher Reference](https://clang.llvm.org/docs/LibASTMatchersReference.html)
+to understand the relationship between the different matcher functions.
+
+### Using the Transformer library
+
+The Transformer library allows you to write a check that transforms source code
+by expressing the transformation as a `RewriteRule`. The Transformer library
+provides functions for composing edits to source code to create rewrite rules.
+Unless you need to perform low-level source location manipulation, you may want
+to consider writing your check with the Transformer library. The [Clang
+Transformer Tutorial](https://clang.llvm.org/docs/ClangTransformerTutorial.html)
+describes the Transformer library in detail.
+
+To use the Transformer library, make the following changes to the code
+generated by the `add_new_check.py` script:
+
+- Include `../utils/TransformerClangTidyCheck.h` instead of
+ `../ClangTidyCheck.h`
+- Change the base class of your check from `ClangTidyCheck` to
+ `TransformerClangTidyCheck`
+- Delete the override of the `registerMatchers` and `check` methods in
+ your check class.
+- Write a function that creates the `RewriteRule` for your check.
+- Call the function in your check's constructor to pass the rewrite rule to
+ `TransformerClangTidyCheck`'s constructor.
+
+### Developing your check incrementally
+
+The best way to develop your check is to start with simple test cases and
+increase complexity incrementally. The test file created by the
+`add_new_check.py` script is a starting point for your test cases.
+A rough outline of the process looks like this:
+
+- Write a test case for your check.
+- Prototype matchers on the test file using {program}`clang-query`.
+- Capture the working matchers in the `registerMatchers` method.
+- Issue the necessary diagnostics and fix-its in the `check` method.
+- Add the necessary `CHECK-MESSAGES` and `CHECK-FIXES` annotations to your
+ test case to validate the diagnostics and fix-its.
+- Build the target `check-clang-tools` to confirm the test passes.
+- Repeat the process until all aspects of your check are covered by tests.
+
+The quickest way to prototype your matcher is to use {program}`clang-query` to
+interactively build up your matcher. For complicated matchers, build up a
+matching expression incrementally and use {program}`clang-query`'s `let`
+command to save named matching expressions to simplify your matcher.
+
+```console
+clang-query> let c1 cxxRecordDecl()
+clang-query> match c1
+```
+
+Alternatively, pressing the tab key after a previous matcher's open parentheses
+would also show which matchers can be chained with the previous matcher,
+though some matchers that work may not be listed. Note that tab completion
+does not currently work on Windows.
+
+Just like breaking up a huge function into smaller chunks with
+intention-revealing names can help you understand a complex algorithm, breaking
+up a matcher into smaller matchers with intention-revealing names can help
+you understand a complicated matcher.
+
+Once you have a working {program}`clang-query` matcher, the C++ API matchers
+will be the same or similar to your interactively constructed matcher (there
+can be cases where they differ slightly). You can use local variables to
+preserve your intention-revealing names that you applied to nested matchers.
+
+### Creating private matchers
+
+Sometimes you want to match a specific aspect of the AST that isn't provided
+by the existing AST matchers. You can create your own private matcher using
+the same infrastructure as the public matchers. A private matcher can
+simplify the processing in your `check` method by eliminating complex
+hand-crafted AST traversal of the matched nodes. Using the private matcher
+allows you to select the desired portions of the AST directly in the matcher
+and refer to it by a bound name in the `check` method.
+
+### Unit testing helper code
+
+Private custom matchers are a good example of auxiliary support code for your
+check that can be tested with a unit test. It will be easier to test your
+matchers or other support classes by writing a unit test than by writing a
+`FileCheck` integration test. The `ASTMatchersTests` target contains unit
+tests for the public AST matcher classes and is a good source of testing
+idioms for matchers.
+
+You can build the Clang-Tidy unit tests by building the `ClangTidyTests`
+target. Test targets in LLVM and Clang are excluded from the "build all" style
+action of IDE-based CMake generators, so you need to explicitly build the
+target for the unit tests to be built.
+
+### Making your check robust
+
+Once you've covered your check with the basic "happy path" scenarios, you'll
+want to torture your check with as many edge cases as you can cover in order to
+ensure your check is robust. Running your check on a large code base, such as
+Clang/LLVM, is a good way to catch things you forgot to account for in your
+matchers. However, the LLVM code base may be insufficient for testing purposes
+as it was developed against a particular set of coding styles and quality
+measures. The larger the corpus of code the check is tested against, the
+higher confidence the community will have in the check's efficacy and
+false-positive rate.
+
+Some suggestions to ensure your check is robust:
+
+- Create header files that contain code matched by your check.
+- Validate that fix-its are properly applied to test header files with
+ {program}`clang-tidy`. You will need to perform this test manually until
+ automated support for checking messages and fix-its is added to the
+ `check_clang_tidy.py` script.
+- Define macros that contain code matched by your check.
+- Define template classes that contain code matched by your check.
+- Define template specializations that contain code matched by your check.
+- Test your check under both Windows and Linux environments. For example, when
+ a fix-it inserts new lines, use the source file's existing newline style
+ instead of hard-coding `\n`. You can use
+ `SourceManager::getBufferData(FileID).detectEOL()` to get the newline style
+ for a file.
+- Watch out for high false-positive rates. Ideally, a check would have no
+ false positives, but given that matching against an AST is not control-
+ or data flow- sensitive, a number of false positives are expected. The
+ higher the false-positive rate, the less likely the check will be adopted
+ in practice. Mechanisms should be put in place to help the user manage
+ false positives.
+- There are two primary mechanisms for managing false positives: suppo...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/234571
More information about the cfe-commits
mailing list