[PATCH] Initial documentation for clang-tidy

[Daniel Jasper]

Hi klimek, chandlerc,

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.

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

Files:
  docs/ClangTidy.rst

Index: docs/ClangTidy.rst
===================================================================
--- /dev/null
+++ docs/ClangTidy.rst
@@ -0,0 +1,42 @@
+=========
+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.
+
-------------- next part --------------
A non-text attachment was scrubbed...
Name: D934.1.patch
Type: text/x-patch
Size: 2482 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20130607/77c5bd71/attachment.bin>