Added documentation for clang-format style options.

Summary:
The main contents is in the ClangFormatStyleOptions.rst, which can be
updated from the Format.h by the dump_format_style.py script.

Reviewers: djasper, klimek

Reviewed By: klimek

CC: cfe-commits

Differential Revision: http://llvm-reviews.chandlerc.com/D1597

llvm-svn: 189946

Author: alexfh

clang/docs/ClangFormat.rst

@@ -70,6 +70,20 @@ to format C/C++/Obj-C code.
     -version                 - Display the version of this program
 
 
+When the desired code formatting style is different from the available options,
+the style can be customized using the ``-style="{key: value, ...}"`` option or
+by putting your style configuration to the ``.clang-format`` file in your
+project's directory and using ``clang-format -style=file``.
+
+An easy way to create the ``.clang-format`` file is:
+
+.. code-block:: console
+
+  clang-format -style=llvm -dump-config > .clang-format
+
+Available style options are described in :doc:`ClangFormatStyleOptions`.
+
+
 Vim Integration
 ===============
 

clang/docs/ClangFormatStyleOptions.rst

@@ -0,0 +1,375 @@
+==========================
+Clang-Format Style Options
+==========================
+
+:doc:`ClangFormatStyleOptions` describes configurable formatting style options
+supported by :doc:`LibFormat` and :doc:`ClangFormat`.
+
+When using :program:`clang-format` command line utility or
+``clang::format::reformat(...)`` functions from code, one can either use one of
+the predefined styles (LLVM, Google, Chromium, Mozilla, WebKit) or create a
+custom style by configuring specific style options.
+
+
+Configuring Style with clang-format
+===================================
+
+:program:`clang-format` supports two ways to provide custom style options:
+directly specify style configuration in the ``-style=`` command line option or
+use ``-style=file`` and put style configuration in the ``.clang-format`` file
+in the project directory.
+
+When using ``-style=file``, :program:`clang-format` for each input file will
+try to find the ``.clang-format`` file located in the closest parent directory
+of the input file. When the standard input is used, the search is started from
+the current directory.
+
+The ``.clang-format`` file uses YAML format:
+
+.. code-block:: yaml
+
+  key1: value1
+  key2: value2
+  # A comment.
+  ...
+
+An easy way to get a valid ``.clang-format`` file containing all configuration
+options of a certain predefined style is:
+
+.. code-block:: console
+
+  clang-format -style=llvm -dump-config > .clang-format
+
+When specifying configuration in the ``-style=`` option, the same configuration
+is applied for all input files. The format of the configuration is:
+
+.. code-block:: console
+
+  -style='{key1: value1, key2: value2, ...}'
+
+
+Configuring Style in Code
+=========================
+
+When using ``clang::format::reformat(...)`` functions, the format is specified
+by supplying the `clang::format::FormatStyle
+<http://clang.llvm.org/doxygen/structclang_1_1format_1_1FormatStyle.html>`_
+structure.
+
+
+Configurable Format Style Options
+=================================
+
+This section lists the supported style options. Value type is specified for
+each option. For enumeration types possible values are specified both as a C++
+enumeration member (with a prefix, e.g. LS_Auto), and as a value usable in the
+configuration (without a prefix).
+
+
+**BasedOnStyle** (``string``)
+  The style used for all options not specifically set in the configuration.
+
+  This option is supported only in the :program:`clang-format` configuration
+  (both within ``-style='{...}'`` and the ``.clang-format`` file).
+
+  Possible values:
+
+  * ``LLVM``
+    A style complying with the `LLVM coding standards
+    <http://llvm.org/docs/CodingStandards.html>`_
+  * ``Google``
+    A style complying with `Google's C++ style guide
+    <http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml>`_
+  * ``Chromium``
+    A style complying with `Chromium's style guide
+    <http://www.chromium.org/developers/coding-style>`_
+  * ``Mozilla``
+    A style complying with `Mozilla's style guide
+    <https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style>`_
+  * ``WebKit``
+    A style complying with `WebKit's style guide
+    <http://www.webkit.org/coding/coding-style.html>`_
+
+.. START_FORMAT_STYLE_OPTIONS
+
+**AccessModifierOffset** (``int``)
+  The extra indent or outdent of access modifiers, e.g. ``public:``.
+
+**AlignEscapedNewlinesLeft** (``bool``)
+  If ``true``, aligns escaped newlines as far left as possible.
+  Otherwise puts them into the right-most column.
+
+**AlignTrailingComments** (``bool``)
+  If ``true``, aligns trailing comments.
+
+**AllowAllParametersOfDeclarationOnNextLine** (``bool``)
+  Allow putting all parameters of a function declaration onto
+  the next line even if ``BinPackParameters`` is ``false``.
+
+**AllowShortIfStatementsOnASingleLine** (``bool``)
+  If ``true``, ``if (a) return;`` can be put on a single
+  line.
+
+**AllowShortLoopsOnASingleLine** (``bool``)
+  If ``true``, ``while (true) continue;`` can be put on a
+  single line.
+
+**AlwaysBreakBeforeMultilineStrings** (``bool``)
+  If ``true``, always break before multiline string literals.
+
+**AlwaysBreakTemplateDeclarations** (``bool``)
+  If ``true``, always break after the ``template<...>`` of a
+  template declaration.
+
+**BinPackParameters** (``bool``)
+  If ``false``, a function call's or function definition's parameters
+  will either all be on the same line or will have one line each.
+
+**BreakBeforeBinaryOperators** (``bool``)
+  If ``true``, binary operators will be placed after line breaks.
+
+**BreakBeforeBraces** (``BraceBreakingStyle``)
+  The brace breaking style to use.
+
+  Possible values:
+
+  * ``BS_Attach`` (in configuration: ``Attach``)
+    Always attach braces to surrounding context.
+  * ``BS_Linux`` (in configuration: ``Linux``)
+    Like ``Attach``, but break before braces on function, namespace and
+    class definitions.
+  * ``BS_Stroustrup`` (in configuration: ``Stroustrup``)
+    Like ``Attach``, but break before function definitions.
+  * ``BS_Allman`` (in configuration: ``Allman``)
+    Always break before braces.
+
+
+**BreakConstructorInitializersBeforeComma** (``bool``)
+  Always break constructor initializers before commas and align
+  the commas with the colon.
+
+**ColumnLimit** (``unsigned``)
+  The column limit.
+
+  A column limit of ``0`` means that there is no column limit. In this case,
+  clang-format will respect the input's line breaking decisions within
+  statements.
+
+**ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``)
+  If the constructor initializers don't fit on a line, put each
+  initializer on its own line.
+
+**ConstructorInitializerIndentWidth** (``unsigned``)
+  The number of characters to use for indentation of constructor
+  initializer lists.
+
+**Cpp11BracedListStyle** (``bool``)
+  If ``true``, format braced lists as best suited for C++11 braced
+  lists.
+
+  Important differences:
+  - No spaces inside the braced list.
+  - No line break before the closing brace.
+  - Indentation with the continuation indent, not with the block indent.
+
+  Fundamentally, C++11 braced lists are formatted exactly like function
+  calls would be formatted in their place. If the braced list follows a name
+  (e.g. a type or variable name), clang-format formats as if the ``{}`` were
+  the parentheses of a function call with that name. If there is no name,
+  a zero-length name is assumed.
+
+**DerivePointerBinding** (``bool``)
+  If ``true``, analyze the formatted file for the most common binding.
+
+**ExperimentalAutoDetectBinPacking** (``bool``)
+  If ``true``, clang-format detects whether function calls and
+  definitions are formatted with one parameter per line.
+
+  Each call can be bin-packed, one-per-line or inconclusive. If it is
+  inconclusive, e.g. completely on one line, but a decision needs to be
+  made, clang-format analyzes whether there are other bin-packed cases in
+  the input file and act accordingly.
+
+  NOTE: This is an experimental flag, that might go away or be renamed. Do
+  not use this in config files, etc. Use at your own risk.
+
+**IndentCaseLabels** (``bool``)
+  Indent case labels one level from the switch statement.
+
+  When ``false``, use the same indentation level as for the switch statement.
+  Switch statement body is always indented one level more than case labels.
+
+**IndentFunctionDeclarationAfterType** (``bool``)
+  If ``true``, indent when breaking function declarations which
+  are not also definitions after the type.
+
+**IndentWidth** (``unsigned``)
+  The number of characters to use for indentation.
+
+**MaxEmptyLinesToKeep** (``unsigned``)
+  The maximum number of consecutive empty lines to keep.
+
+**NamespaceIndentation** (``NamespaceIndentationKind``)
+  The indentation used for namespaces.
+
+  Possible values:
+
+  * ``NI_None`` (in configuration: ``None``)
+    Don't indent in namespaces.
+  * ``NI_Inner`` (in configuration: ``Inner``)
+    Indent only in inner namespaces (nested in other namespaces).
+  * ``NI_All`` (in configuration: ``All``)
+    Indent in all namespaces.
+
+
+**ObjCSpaceBeforeProtocolList** (``bool``)
+  Add a space in front of an Objective-C protocol list, i.e. use
+  ``Foo <Protocol>`` instead of ``Foo<Protocol>``.
+
+**PenaltyBreakComment** (``unsigned``)
+  The penalty for each line break introduced inside a comment.
+
+**PenaltyBreakFirstLessLess** (``unsigned``)
+  The penalty for breaking before the first ``<<``.
+
+**PenaltyBreakString** (``unsigned``)
+  The penalty for each line break introduced inside a string literal.
+
+**PenaltyExcessCharacter** (``unsigned``)
+  The penalty for each character outside of the column limit.
+
+**PenaltyReturnTypeOnItsOwnLine** (``unsigned``)
+  Penalty for putting the return type of a function onto its own
+  line.
+
+**PointerBindsToType** (``bool``)
+  Set whether & and * bind to the type as opposed to the variable.
+
+**SpaceAfterControlStatementKeyword** (``bool``)
+  If ``true``, spaces will be inserted between 'for'/'if'/'while'/...
+  and '('.
+
+**SpaceInEmptyParentheses** (``bool``)
+  If ``false``, spaces may be inserted into '()'.
+
+**SpacesBeforeTrailingComments** (``unsigned``)
+  The number of spaces to before trailing line comments.
+
+**SpacesInCStyleCastParentheses** (``bool``)
+  If ``false``, spaces may be inserted into C style casts.
+
+**SpacesInParentheses** (``bool``)
+  If ``true``, spaces will be inserted after every '(' and before
+  every ')'.
+
+**Standard** (``LanguageStandard``)
+  Format compatible with this standard, e.g. use
+  ``A<A<int> >`` instead of ``A<A<int>>`` for LS_Cpp03.
+
+  Possible values:
+
+  * ``LS_Cpp03`` (in configuration: ``Cpp03``)
+    Use C++03-compatible syntax.
+  * ``LS_Cpp11`` (in configuration: ``Cpp11``)
+    Use features of C++11 (e.g. ``A<A<int>>`` instead of
+    ``A<A<int> >``).
+  * ``LS_Auto`` (in configuration: ``Auto``)
+    Automatic detection based on the input.
+
+
+**UseTab** (``bool``)
+  If ``true``, ``IndentWidth`` consecutive spaces will be replaced
+  with tab characters.
+
+.. END_FORMAT_STYLE_OPTIONS
+
+Examples
+========
+
+A style similar to the `Linux Kernel style
+<https://www.kernel.org/doc/Documentation/CodingStyle>`_:
+
+.. code-block:: yaml
+
+  BasedOnStyle: LLVM
+  IndentWidth: 8
+  UseTab: true
+  BreakBeforeBraces: Linux
+  AllowShortIfStatementsOnASingleLine: false
+  IndentCaseLabels: false
+
+The result is (imagine that tabs are used for indentation here):
+
+.. code-block:: c++
+
+  void test()
+  {
+          switch (x) {
+          case 0:
+          case 1:
+                  do_something();
+                  break;
+          case 2:
+                  do_something_else();
+                  break;
+          default:
+                  break;
+          }
+          if (condition)
+                  do_something_completely_different();
+
+          if (x == y) {
+                  q();
+          } else if (x > y) {
+                  w();
+          } else {
+                  r();
+          }
+  }
+
+A style similar to the default Visual Studio formatting style:
+
+.. code-block:: yaml
+
+  UseTab: false
+  IndentWidth: 4
+  BreakBeforeBraces: Allman
+  AllowShortIfStatementsOnASingleLine: false
+  IndentCaseLabels: false
+  ColumnLimit: 0
+
+The result is:
+
+.. code-block:: c++
+
+  void test()
+  {
+      switch (suffix)
+      {
+      case 0:
+      case 1:
+          do_something();
+          break;
+      case 2:
+          do_something_else();
+          break;
+      default:
+          break;
+      }
+      if (condition)
+          do_somthing_completely_different();
+
+      if (x == y)
+      {
+          q();
+      }
+      else if (x > y)
+      {
+          w();
+      }
+      else
+      {
+          r();
+      }
+  }
+