[include-fixer] Add basic documentation.

[bkramer]

de-freud

[hokein]

docs/include-fixer.rst

37

A extra space before a.

49

We should also create a link to compile_commands.json in path/to/llvm/source/.

[bkramer]

Address review comments.

[bkramer]

docs/include-fixer.rst

49

If the user followed the instructions at http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html the link will be there already. I'll add it here with a clarifying comment.

[klimek]

lg

docs/include-fixer.rst

17

s/, b/. B/

docs/include-fixer.rst

+===================
+Clang-Include-Fixer
+===================
+
+.. contents::
+
+One of the major nuisances of C++ compared to other languages is the manual
+management of ``#include`` directives in any file.
+:program:`clang-include-fixer` addresses one aspect of this problem by providing
+an automated way of adding ``#include`` directives for missing symbols in one
+translation unit.
+
+Setup
+=====
+
+To use :program:`clang-include-fixer` two databases are required, both can be
+generated with existing tools.
+
+- Compilation database. Contains the compiler commands for any given file in a
+  project and can be generated by CMake, see `How To Setup Tooling For LLVM`_.
+- Xrefs database. Contains all symbol information in a project to match a given
+  identifier to a header file.
+
+Ideally both databases (``compile_commands.json`` and
+``find_all_symbols_db.yaml``) are linked into the root of the source tree they
+correspond to. Then the :program:`clang-include-fixer` can automatically pick
+them up if called with a source file from that tree. Note that by default
+``compile_commands.json`` as generated by CMake does not include header files,
+so only implementation files can be handled by tools.
+
+.. _How To Setup Tooling For LLVM: http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html
+
+Creating an Xrefs Database From a Compilation Database
+------------------------------------------------------
+
+The include fixer contains :program:`find-all-symbols`, a tool to create a
+symbol database in YAML format from a compilation database by parsing all
+source files listed in it. The following list of commands shows how to set up a
+database for LLVM, any project built by CMake should follow similar steps.
+
+.. code-block:: console
+
+  $ cd path/to/llvm-build
+  $ ls compile_commands.json # Make sure compile_commands.json exists.
+    compile_commands.json
+  $ path/to/llvm/source/tools/clang/tools/extra/include-fixer/find-all-symbols/tool/run-find-all-symbols.py
+    ... wait as clang indexes the code base ...
+  $ ln -s $PWD/find_all_symbols_db.yaml path/to/llvm/source/ # Link database into the source tree.
+  $ ln -s $PWD/compile_commands.json path/to/llvm/source/ # Also link compilation database if it's not there already.
+  $ cd path/to/llvm/source
+  $ clang-include-fixer -db=yaml path/to/file/with/missing/include.cpp
+    Added #include "foo.h"
+
+How it Works
+============
+
+To get the most information out of clang at parse time,
+:program:`clang-include-fixer` runs in tandem with the parse and receives
+callbacks from Clang's semantic analysis. In particular it reuses the existing
+support for typo corrections. Whenever Clang tries to correct a potential typo
+it emits a callback to the include fixer which then looks for a corresponding
+file. At this point rich lookup information is still available, which is not
+available in the AST at a later stage.
+
+The identifier that should be typo corrected is then sent to the database, if a
+header file is returned it is added as an include directive at the top of the
+file.
+
+Currently :program:`clang-include-fixer` only inserts a single include at a
+time to avoid getting caught in follow-up errors. If multiple `#include`
+additions are desired the program can be rerun until a fix-point is reached.

docs/index.rst

.. toctree::
    ReleaseNotes
 
 Contents
 ========
 .. toctree::
    :maxdepth: 2
 
    clang-tidy/index
+   include-fixer
    modularize
    pp-trace
 
 
 Doxygen Documentation
 =====================
 The Doxygen documentation describes the **internal** software that makes up the
 tools of clang-tools-extra, not the **external** use of these tools. The Doxygen