Initial documentation for clang-tidy

[djasper]

Summary

This is in relation to the proposed patch in
http://llvm-reviews.chandlerc.com/D884

It gathers initial thoughts on the design of clang-tidy. Similar to the patch itself, this doc is meant as an initial design and might be heavily in flux while details of clang-tidy are mapped out.

[silvas]

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.

docs/ClangTidy.rst

5–7

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).

9–11

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).

11–13

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.

15

spelling: infrastructure.

17–19

I think some part of this sentence got lost.

37–41

This would be good as a subsection of the "checks" section.

[djasper]

Superseded by Alex's docs.

docs/ClangTidy.rst

+=========
+ClangTidy
+=========
+
+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.
+
+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
+of checks used for a specific project.
+
+A check can use different parts of Clang's infrastructer. For example a check
+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>`.
+
+When invoked, ``clang-tidy`` runs all the configured checks on a specified set
+of source code. Similar to other :doc:`ClangTools <ClangTools>`, it will
+usually use a project's compilation database, in order to figure out how to
+build a specific source file. It can be configured to only analyze specific
+ranges in specific files and ignore any errors outside of those ranges. This is
+particularly useful when making changes to an existing project, which might not
+be ``clang-tidy``-clean.
+
+If possible, a ``clang-tidy``-check will not only warn on specific code
+patterns, but it will also create the changes necessary to fix the code. E.g.,
+these changes could be a re-ordering of the #includes or the addition of a
+for-loop variable initialized to ``end()``. ``clang-tidy`` will collect the
+fixes from all checks, possibly detect conflicts and duplicates, and apply them
+to the source code. It will then invoke :doc:`ClangFormat <ClangFormat>` to
+ensure that the source code is left in a well-formatted state.
+
+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.
+