[PATCH] Initial documentation for clang-tidy

[Sean Silva]

  This is really good content. I think the biggest thing needed is organization (sections) and examples (especially of how typical usage of clang-tidy will look to the end-user; for now we can focus on command-line usage; what is a typical use case?).

  Also, please add an intro section following the guidelines set out in the SphinxQuickstartTemplate <http://llvm.org/docs/SphinxQuickstartTemplate.html#guidelines>.


================
Comment at: docs/ClangTidy.rst:15
@@ +14,3 @@
+
+A check can use different parts of Clang's infrastructer. For example a check
+that verifies the alphabetical order of #includes will probably use
----------------
spelling: infrastructure.

================
Comment at: docs/ClangTidy.rst:17-19
@@ +16,5 @@
+that verifies the alphabetical order of #includes will probably use
+preprocessor callbacks. A check that verifies that ``end()`` in every for-loop
+iteration (see LLVM Coding Standards) will make use of Clang's AST and the
+:doc:`ASTMatchers <LibASTMatchers>`.
+
----------------
I think some part of this sentence got lost.

================
Comment at: docs/ClangTidy.rst:11-13
@@ +10,5 @@
+extended to check the specific coding patterns used in a given project. To this
+end, it is organized into *checks* and *modules*. Each check verifies the
+adherence to a specific pattern. Each module configures and combines a number
+of checks used for a specific project.
+
----------------
It's not entirely clear to me what "module" is from this description. Is it the end-user setting that a project specifies (e.g., LLVM just uses the "llvm" module, which aggregates all of the checks that LLVM wants), or are they another building block that are combinable themselves? The name "module" makes it sound like the latter, but the description makes it seem like the former. Maybe a different name would be good?

Assuming the "end-user project-wide setting" interpretation of "module", does it make sense to say "organized into checks and modules"? To me, that makes it sound like a hierarchical namespace, when the conceptual relationship (from my understanding) is more like a pool of "checks", with "modules" aggregating some subset of the checks. I.e., two modules may contain some of the same checks.

Possibly also mention parallels with clang-format's configuration (which AFAIK is similarly organized); since this tool calls clang-format as part of its operation in a lot of cases, so the user probably already has it set up.

================
Comment at: docs/ClangTidy.rst:5-7
@@ +4,5 @@
+
+The :doc:`ClangTool <ClangTools>` ``clang-tidy`` analyzes source code and
+detects errors in adhering to common coding patterns, e.g. described in the
+LLVM Coding Standards.
+
----------------
I think the aspect of automatically or semi-automatically fixing coding standard violations is worth mentioning here, along with the dependence on clang-format for that capability (we don't want people getting too far and then be derailed setting up clang-format for their project).

================
Comment at: docs/ClangTidy.rst:9-11
@@ +8,5 @@
+
+The design of ``clang-tidy`` aims to be very flexible so that it can easily be
+extended to check the specific coding patterns used in a given project. To this
+end, it is organized into *checks* and *modules*. Each check verifies the
+adherence to a specific pattern. Each module configures and combines a number
----------------
This paragraph is kind of confusing. The first sentence is about clang-tidy's flexibility, then the next sentence is an assertion about how clang-tidy's particular organization enables that, but then there is no discussion of how or why this organization enables that flexibility. If you aren't going to support this claim, just leave it out. Instead, focus on checks and modules individually (probably, give each one its own section/subsection).


================
Comment at: docs/ClangTidy.rst:37-41
@@ +36,7 @@
+
+Some checks might not be entirely safe. For example, it might be necessary to
+evaluate ``end()`` every time through a loop iteration. Thus, the warnings and
+fixes generated by a specific checks will need a kind of confidence level. When
+invoking ``clang-tidy``, the confidence levels for warnings and fixes can be
+specified and ``clang-tidy`` will ignore everything that is less safe.
+
----------------
This would be good as a subsection of the "checks" section.


http://llvm-reviews.chandlerc.com/D934