Add documentation for clang-format.

This adds documentation for both LibFormat as well as the standalone
tools and integrations built on top of it. It slightly restructures
the ClangTools documentation.

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@172004 91177308-0d34-0410-b5e6-96231b3b80d8

docs/ClangCheck.rst

@@ -0,0 +1,36 @@
+==========
+ClangCheck
+==========
+
+`ClangCheck` is a small wrapper around :doc:`LibTooling` which can be used to
+do basic error checking and AST dumping.
+
+.. code-block:: console
+
+  $ cat <<EOF > snippet.cc
+  > void f() {
+  >   int a = 0
+  > }
+  > EOF
+  $ ~/clang/build/bin/clang-check snippet.cc -ast-dump --
+  Processing: /Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc.
+  /Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:2:12: error: expected ';' at end of
+        declaration
+    int a = 0
+             ^
+             ;
+  (TranslationUnitDecl 0x7ff3a3029ed0 <<invalid sloc>>
+    (TypedefDecl 0x7ff3a302a410 <<invalid sloc>> __int128_t '__int128')
+    (TypedefDecl 0x7ff3a302a470 <<invalid sloc>> __uint128_t 'unsigned __int128')
+    (TypedefDecl 0x7ff3a302a830 <<invalid sloc>> __builtin_va_list '__va_list_tag [1]')
+    (FunctionDecl 0x7ff3a302a8d0 </Users/danieljasper/clang/llvm/tools/clang/docs/snippet.cc:1:1, line:3:1> f 'void (void)'
+      (CompoundStmt 0x7ff3a302aa10 <line:1:10, line:3:1>
+        (DeclStmt 0x7ff3a302a9f8 <line:2:3, line:3:1>
+          (VarDecl 0x7ff3a302a980 <line:2:3, col:11> a 'int'
+            (IntegerLiteral 0x7ff3a302a9d8 <col:11> 'int' 0))))))
+  1 error generated.
+  Error while processing snippet.cc.
+
+The '--' at the end is important as it prevents `clang-check` from search for a
+compilation database. For more information on how to setup and use `clang-check`
+in a project, see :doc:`HowToSetupToolingForLLVM`.

docs/ClangFormat.rst

@@ -0,0 +1,94 @@
+===========
+ClangFormat
+===========
+
+`ClangFormat` describes a set of tools that are built on top of
+:doc:`LibFormat`. It can support your workflow in a variety of ways including a
+standalone tool and editor integrations.
+
+
+Standalone Tool
+===============
+
+`clang-format` is part of the `clang/tools/extra` (see
+:doc:`ClangTools <ClangTools>`) repository and can be used to format
+C/C++/Obj-C code.
+
+.. code-block:: console
+
+  $ clang-format --help
+  OVERVIEW: A tool to format C/C++/Obj-C code.
+
+  Currently supports LLVM and Google style guides.
+  If no arguments are specified, it formats the code from standard input
+  and writes the result to the standard output.
+  If <file> is given, it reformats the file. If -i is specified together
+  with <file>, the file is edited in-place. Otherwise, the result is
+  written to the standard output.
+
+  USAGE: clang-format [options] [<file>]
+
+  OPTIONS:
+    -fatal-assembler-warnings - Consider warnings as error
+    -help                     - Display available options (-help-hidden for more)
+    -i                        - Inplace edit <file>, if specified.
+    -length=<int>             - Format a range of this length, -1 for end of file.
+    -offset=<int>             - Format a range starting at this file offset.
+    -stats                    - Enable statistics output from program
+    -style=<string>           - Coding style, currently supports: LLVM, Google.
+    -version                  - Display the version of this program
+
+
+Vim Integration
+===============
+
+There is an integration for `vim` which lets you run the `clang-format`
+standalone tool on your current buffer, optionally selecting regions to
+reformat. The integration has to form of a `python`-file which can be found
+under `clang/tools/extra/clang-format/clang-format.py`.
+
+This can be integrated by mapping the following to your `.vimrc`:
+
+.. code-block:: console
+
+  map <C-I> :pyf <path-to-this-file>/clang-format.py<CR>
+  imap <C-I> <ESC>:pyf <path-to-this-file>/clang-format.py<CR>i
+
+The first line enables `clang-format` for NORMAL and VISUAL mode, the second
+line adds support for INSER` mode. Change "C-I" to another binding if you
+need clang-format on a different key (C-I stands for Ctrl+i).
+
+With this integration you can press the bound key and clang-format will
+format the current line in NORMAL and INSERT mode or the selected region in
+VISUAL mode. The line or region is extended to the next bigger syntactic
+entity.
+
+It operates on the current, potentially unsaved buffer and does not create
+or save any files. To revert a formatting, just undo.
+
+
+Script for patch reformatting
+=============================
+
+The python script `clang/tools/extra/clang-format-diff.py` parses the output of
+a unified diff and reformats all contained lines with `clang-format`.
+
+.. code-block:: console
+
+  usage: clang-format-diff.py [-h] [-p P] [-style STYLE]
+
+  Reformat changed lines in diff
+
+  optional arguments:
+    -h, --help    show this help message and exit
+    -p P          strip the smallest prefix containing P slashes
+    -style STYLE  formatting style to apply (LLVM, Google)
+
+So to reformat all the lines in the latest `git` commit, just do:
+
+.. code-block:: console
+
+  git diff -U0 HEAD^ | clang-format-diff.py
+  
+The `-U0` will create a diff without context lines (the script would format
+those as well).

docs/ClangTools.rst

@@ -1,9 +1,9 @@
-===========
-Clang Tools
-===========
+========
+Overview
+========
 
 Clang Tools are standalone command line (and potentially GUI) tools
-design for use by C++ developers who are already using and enjoying
+designed for use by C++ developers who are already using and enjoying
 Clang as their compiler. These tools provide developer-oriented
 functionality such as fast syntax checking, automatic formatting,
 refactoring, etc.
@@ -73,14 +73,25 @@ tools that very specifically compliment, and allow use and testing of
 ``clang-check``
 ---------------
 
-This tool combines the LibTooling framework for running a Clang tool
-with the basic Clang diagnostics by syntax checking specific files in a
-fast, command line interface. It can also accept flags to re-display the
-diagnostics in different formats with different flags, suitable for use
-driving an IDE or editor. Furthermore, it can be used in fixit-mode to
-directly apply fixit-hints offered by clang.
+:doc:`ClangCheck` combines the LibTooling framework for running a
+Clang tool with the basic Clang diagnostics by syntax checking specific files
+in a fast, command line interface. It can also accept flags to re-display the
+diagnostics in different formats with different flags, suitable for use driving
+an IDE or editor. Furthermore, it can be used in fixit-mode to directly apply
+fixit-hints offered by clang. See :doc:`HowToSetupToolingForLLVM` for
+instructions on how to setup and used `clang-check`.
 
-FIXME: Link to user-oriented clang-check documentation.
+``clang-format``
+~~~~~~~~~~~~~~~~
+
+Clang-format is both a :doc:`library <LibFormat>` and a :doc:`stand-alone tool
+<ClangFormat>` with the goal of automatically reformatting C++ sources files
+according to configurable style guides. To do so, clang-format users Clang's
+Lexer to transform an input file into a token stream and then changes all the
+whitespace around those tokens.  The goal is for clang-format to both serve
+both as a user tool (ideally with powerful IDE integrations) and part of other
+refactoring tools, e.g. to do a reformatting of all the lines changed during a
+renaming.
 
 Extra Clang Tools
 =================

docs/LibFormat.rst

@@ -0,0 +1,56 @@
+=========
+LibFormat
+=========
+
+LibFormat is a library that implements automatic source code formatting based
+on Clang. This documents describes the LibFormat interface and design as well
+as some basic style discussions.
+
+If you just want to use `clang-format` as a tool or integrated into an editor,
+checkout :doc:`ClangFormat`.
+
+Design
+------
+
+FIXME: Write up design.
+
+
+Interface
+---------
+
+The core routine of LibFormat is ``reformat()``:
+
+.. code-block:: c++
+
+  tooling::Replacements reformat(const FormatStyle &Style, Lexer &Lex,
+                                 SourceManager &SourceMgr,
+                                 std::vector<CharSourceRange> Ranges);
+
+This reads a token stream out of the lexer ``Lex`` and reformats all the code
+ranges in ``Ranges``. The ``FormatStyle`` controls basic decisions made during
+formatting. A list of options can be found under :ref:`style-options`. 
+
+
+.. _style-options:
+
+Style Options
+-------------
+
+The style options describe specific formatting options that can be used in
+order to make `ClangFormat` comply with different style guides. Currently,
+two style guides are hard-coded:
+
+.. code-block:: c++
+
+  /// \brief Returns a format style complying with the LLVM coding standards:
+  /// http://llvm.org/docs/CodingStandards.html.
+  FormatStyle getLLVMStyle();
+
+  /// \brief Returns a format style complying with Google's C++ style guide:
+  /// http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml.
+  FormatStyle getGoogleStyle();
+
+These options are also exposed in the :doc:`standalone tools <ClangFormat>`
+through the `-style` option.
+
+In the future, we plan on making this configurable.

docs/index.rst

@@ -32,14 +32,24 @@ Using Clang as a Library
    Tooling
    IntroductionToTheClangAST
    LibTooling
+   LibFormat
    ClangPlugins
    RAVFrontendAction
    LibASTMatchersTutorial
    LibASTMatchers
-   ClangTools
    HowToSetupToolingForLLVM
    JSONCompilationDatabase
 
+Using Clang Tools
+=================
+
+.. toctree::
+   :maxdepth: 1
+
+   ClangTools
+   ClangCheck
+   ClangFormat
+
 Design Documents
 ================