Author: alexfh
Date: Wed Nov 9 14:03:30 2016
New Revision: 286390
URL: http://llvm.org/viewvc/llvm-project?rev=286390&view=rev
Log:
[clang-tidy docs] Recommend using add_new_check.py more
Modified:
clang-tools-extra/trunk/docs/clang-tidy/index.rst
Modified: clang-tools-extra/trunk/docs/clang-tidy/index.rst
URL:
http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/clang-tidy/index.rst?rev=286390&r1=286389&r2=286390&view=diff
==============================================================================
--- clang-tools-extra/trunk/docs/clang-tidy/index.rst (original)
+++ clang-tools-extra/trunk/docs/clang-tidy/index.rst Wed Nov 9 14:03:30 2016
@@ -352,43 +352,58 @@ readability, etc.), certain coding style
or a widely used API (e.g. MPI). Their names are same as user-facing check
groups names described :ref:`above <checks-groups-table>`.
-After choosing the module, you need to create a class for your check:
+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 clang-tidy. It's the recommended way of adding new checks.
+
+If we want to create a `readability-awesome-function-names`, we would run:
+
+.. code-block:: 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.rst``.
+
+Let's see in more detail at the check class definition:
.. code-block:: c++
+ ...
+
#include "../ClangTidy.h"
namespace clang {
namespace tidy {
- namespace some_module {
+ namespace readability {
- class MyCheck : public ClangTidyCheck {
+ ...
+ class AwesomeFunctionNamesCheck : public ClangTidyCheck {
public:
- MyCheck(StringRef Name, ClangTidyContext *Context)
+ AwesomeFunctionNamesCheck(StringRef Name, ClangTidyContext *Context)
: ClangTidyCheck(Name, Context) {}
+ void registerMatchers(ast_matchers::MatchFinder *Finder) override;
+ void check(const ast_matchers::MatchFinder::MatchResult &Result) override;
};
- } // namespace some_module
+ } // namespace readability
} // namespace tidy
} // namespace clang
+ ...
+
Constructor of the check receives the ``Name`` and ``Context`` parameters, and
must forward them to the ``ClangTidyCheck`` constructor.
-Next, you need to decide whether it should operate on the preprocessor level or
-on the AST level. Let's imagine that we need to work with the AST in our check.
-In this case we need to override two methods:
-
-.. code-block:: c++
-
- ...
- class ExplicitConstructorCheck : public ClangTidyCheck {
- public:
- ExplicitConstructorCheck(StringRef Name, ClangTidyContext *Context)
- : ClangTidyCheck(Name, Context) {}
- void registerMatchers(ast_matchers::MatchFinder *Finder) override;
- void check(ast_matchers::MatchFinder::MatchResult &Result) override;
- };
+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`_
for more information) that will find the pattern in the AST that we want to
@@ -399,24 +414,20 @@ can further inspect them and report diag
using namespace ast_matchers;
- void ExplicitConstructorCheck::registerMatchers(MatchFinder *Finder) {
- Finder->addMatcher(constructorDecl().bind("ctor"), this);
+ void AwesomeFunctionNamesCheck::registerMatchers(MatchFinder *Finder) {
+ Finder->addMatcher(functionDecl().bind("x"), this);
}
- void ExplicitConstructorCheck::check(const MatchFinder::MatchResult &Result)
{
- const auto *Ctor = Result.Nodes.getNodeAs<CXXConstructorDecl>("ctor");
- // Do not be confused: isExplicit means 'explicit' keyword is present,
- // isImplicit means that it's a compiler-generated constructor.
- if (Ctor->isOutOfLine() || Ctor->isExplicit() || Ctor->isImplicit())
+ void AwesomeFunctionNamesCheck::check(const MatchFinder::MatchResult
&Result) {
+ const auto *MatchedDecl = Result.Nodes.getNodeAs<FunctionDecl>("x");
+ if (MatchedDecl->getName().startswith("awesome_"))
return;
- if (Ctor->getNumParams() == 0 || Ctor->getMinRequiredArguments() > 1)
- return;
- SourceLocation Loc = Ctor->getLocation();
- diag(Loc, "single-argument constructors must be explicit")
- << FixItHint::CreateInsertion(Loc, "explicit ");
+ diag(MatchedDecl->getLocation(), "function %0 is insufficiently awesome")
+ << MatchedDecl
+ << FixItHint::CreateInsertion(MatchedDecl->getLocation(), "awesome_");
}
-(The full code for this check resides in
+(If you want to see an example of a useful check, look at
`clang-tidy/google/ExplicitConstructorCheck.h
<http://reviews.llvm.org/diffusion/L/browse/clang-tools-extra/trunk/clang-tidy/google/ExplicitConstructorCheck.h>`_
and `clang-tidy/google/ExplicitConstructorCheck.cpp
@@ -426,6 +437,9 @@ and `clang-tidy/google/ExplicitConstruct
Registering your Check
----------------------
+(The ``add_new_check.py`` takes care of registering the check in an existing
+module. If you want to create a new module or know the details, read on.)
+
The check should be registered in the corresponding module with a distinct
name:
.. code-block:: c++
@@ -511,7 +525,7 @@ be set in a ``.clang-tidy`` file in the
If you need to specify check options on a command line, you can use the inline
YAML format:
-.. code-block:: bash
+.. code-block:: console
$ clang-tidy -config="{CheckOptions: [{key: a, value: b}, {key: x, value:
y}]}" ...
@@ -540,7 +554,7 @@ substitutions and distinct function and
Here's an example of a test using the ``check_clang_tidy.py`` script (the full
source code is at `test/clang-tidy/google-readability-casting.cpp`_):
-.. code-block:: bash
+.. code-block:: c++
// RUN: %check_clang_tidy %s google-readability-casting %t
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
