[clang-tools-extra] r218570 - [clang-tidy] Updated documentation.

[Alexander Kornienko]

Author: alexfh
Date: Sat Sep 27 16:25:26 2014
New Revision: 218570

URL: http://llvm.org/viewvc/llvm-project?rev=218570&view=rev
Log:
[clang-tidy] Updated documentation.

Modified:
    clang-tools-extra/trunk/docs/clang-tidy.rst

Modified: clang-tools-extra/trunk/docs/clang-tidy.rst
URL: http://llvm.org/viewvc/llvm-project/clang-tools-extra/trunk/docs/clang-tidy.rst?rev=218570&r1=218569&r2=218570&view=diff
==============================================================================
--- clang-tools-extra/trunk/docs/clang-tidy.rst (original)
+++ clang-tools-extra/trunk/docs/clang-tidy.rst Sat Sep 27 16:25:26 2014
@@ -94,11 +94,33 @@ An overview of all the command-line opti
                                with matching names to the set, globs with the '-'
                                prefix remove checks with matching names from the
                                set of enabled checks.
+                               This option's value is appended to the value read
+                               from a .clang-tidy file, if any.
+    -config=<string>         - Specifies a configuration in YAML/JSON format:
+                                 -config="{Checks: '*', CheckOptions: {key: x, value: 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.
+    -dump-config             - Dumps configuration in the YAML format to stdout.
+    -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.
     -fix                     - Fix detected errors if possible.
     -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.
+                               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 value read from a
+                               .clang-tidy file.
+    -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:
+                                 [
+                                   {"name":"file1.cpp","lines":[[1,3],[5,7]]},
+                                   {"name":"file2.h"}
+                                 ]
     -list-checks             - List all enabled checks and exit. Use with
                                -checks='*' to list all available checks.
     -p=<string>              - Build path
@@ -122,6 +144,12 @@ An overview of all the command-line opti
     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 any configuration options have a corresponding command-line
+    option, command-line option takes precedence. The effective
+    configuration can be inspected using -dump-config.
 
 .. _LibTooling: http://clang.llvm.org/docs/LibTooling.html
 .. _How To Setup Tooling For LLVM: http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html
@@ -247,10 +275,15 @@ In this case we need to override two met
   ...
   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;
   };
 
+Constructor of the check receives the ``Name`` and ``Context`` parameters, and
+must forward them to the ``ClangTidyCheck`` constructor.
+
 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
 inspect. The results of the matching are passed to the ``check`` method, which
@@ -279,7 +312,7 @@ can further inspect them and report diag
   }
 
 (The full code for this check resides in
-``clang-tidy/google/GoogleTidyModule.cpp``).
+``clang-tidy/google/ExplicitConstructorCheck.{h,cpp}``).
 
 
 Registering your Check
@@ -292,9 +325,8 @@ The check should be registered in the co
   class MyModule : public ClangTidyModule {
    public:
     void addCheckFactories(ClangTidyCheckFactories &CheckFactories) override {
-      CheckFactories.addCheckFactory(
-          "my-explicit-constructor",
-          new ClangTidyCheckFactory<ExplicitConstructorCheck>());
+      CheckFactories.registerCheck<ExplicitConstructorCheck>(
+          "my-explicit-constructor");
     }
   };
 
@@ -328,6 +360,33 @@ you link the ``clang-tidy`` library in)
   static int MyModuleAnchorDestination = MyModuleAnchorSource;
 
 
+Configuring Checks
+------------------
+
+If a check needs configuration options, it can access check-specific options
+using the ``Options.get<Type>("SomeOption", DefaultValue)`` call in the check
+constructor. In this case the check should also override the
+``ClangTidyCheck::storeOptions`` method to make the options provided by the
+check discoverable. This method lets :program:`clang-tidy` know which options
+the check implements and what the current values are (e.g. for the
+``-dump-config`` command line option).
+
+.. code-block:: c++
+
+  class MyCheck : public ClangTidyCheck {
+    const unsigned SomeOption;
+  
+  public:
+    MyCheck(StringRef Name, ClangTidyContext *Context)
+      : ClangTidyCheck(Name, Context),
+        SomeOption(Options.get("SomeOption", -1U)) {}
+
+    void storeOptions(ClangTidyOptions::OptionMap &Opts) {
+      Options.store(Opts, "SomeOption", SomeOption);
+    }
+    ...
+
+
 Running clang-tidy on LLVM
 --------------------------