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