[clang-tools-extra] r286390 - [clang-tidy docs] Recommend using add_new_check.py more

[Alexander Kornienko via cfe-commits]

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