[clang-format] Update documentation

[thakis]

Summary

• Update clang-format --help output after b1f0efc06acc.
• Update clang-format-diff.py help text, which apparently hasn't been updated in a while. Since git and svn examples are now part of the help text, remove them in the text following the help text.

[thakis]

clang/docs/ClangFormat.rst

233

(As far as I can tell, we don't have git clang-format docs anywhere? But that's for a different patch.)

[owenpan]

clang/docs/ClangFormat.rst

20

This should be edited in dump_format_help.py instead.

[rymiel]

NOTE: Clang-Format Team Automated Review Comment

It looks like your clang-format review does not contain any unit tests, please try to ensure all code changes have a unit test (unless this is an NFC or refactoring, adding documentation etc..)

Add your unit tests in clang/unittests/Format and you can build with ninja FormatTests. We recommend using the verifyFormat(xxx) format of unit tests rather than EXPECT_EQ as this will ensure you change is tolerant to random whitespace changes (see FormatTest.cpp as an example)

For situations where your change is altering the TokenAnnotator.cpp which can happen if you are trying to improve the annotation phase to ensure we are correctly identifying the type of a token, please add a token annotator test in TokenAnnotatorTest.cpp

[owenpan]

clang/docs/ClangFormat.rst

20

Fixed in c47c480b1845.

clang/docs/ClangFormat.rst

 
 :program:`clang-format` is located in `clang/tools/clang-format` and can be used
 to format C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# code.
 
 .. START_FORMAT_HELP
 
 .. code-block:: console
 
-  $ clang-format -help
+  $ clang-format --help
   OVERVIEW: A tool to format C/C++/Java/JavaScript/JSON/Objective-C/Protobuf/C# code.
 
   If no arguments are specified, it formats the code from standard input
   and writes the result to the standard output.
   If <file>s are given, it reformats the files. If -i is specified
   together with <file>s, the files are edited in-place. Otherwise, the
   result is written to the standard output.
 
   USAGE: clang-format [options] [<file> ...]
 
   OPTIONS:
 
   Clang-format options:
 
     --Werror                       - If set, changes formatting warnings to errors
     --Wno-error=<value>            - If set don't error out on the specified warning type.
       =unknown                     -   If set, unknown format options are only warned about.
                                        This can be used to enable formatting, even if the
                                        configuration contains unknown (newer) options.
                                        Use with caution, as this might lead to dramatically
                                        differing format depending on an option being
                                        supported or not.
-    --assume-filename=<string>     - Override filename used to determine the language.
-                                     When reading from stdin, clang-format assumes this
-                                     filename to determine the language.
+    --assume-filename=<string>     - Set filename used to determine the language and to find
+                                     .clang-format file.
+                                     Only used when reading from stdin.
+                                     If this is not passed, the .clang-format file is searched
+                                     relative to the current working directory when reading stdin.
                                      Unrecognized filenames are treated as C++.
                                      supported:
                                        CSharp: .cs
                                        Java: .java
                                        JavaScript: .mjs .js .ts
                                        Json: .json
                                        Objective-C: .m .mm
                                        Proto: .proto .protodevel
                                        TableGen: .td
                                        TextProto: .textpb .pb.txt .textproto .asciipb
                                        Verilog: .sv .svh .v .vh
     --cursor=<uint>                - The position of the cursor when invoking
                                      clang-format from an editor integration
     --dry-run                      - If set, do not actually make the formatting changes
     --dump-config                  - Dump configuration options to stdout and exit.
                                      Can be used with -style option.
     --fallback-style=<string>      - The name of the predefined style used as a
                                      fallback in case clang-format is invoked with
                                      -style=file, but can not find the .clang-format
-                                     file to use.
+                                     file to use. Defaults to 'LLVM'.
                                      Use -fallback-style=none to skip formatting.
     --ferror-limit=<uint>          - Set the maximum number of clang-format errors to emit
                                      before stopping (0 = no limit).
                                      Used only with --dry-run or -n
     --files=<string>               - Provide a list of files to run clang-format
     -i                             - Inplace edit <file>s, if specified.
     --length=<uint>                - Format a range of this length (in bytes).
                                      Multiple ranges can be formatted by specifying
--offset=<uint>                - Format a range starting at this byte offset.
                                      Multiple ranges can be formatted by specifying
                                      several -offset and -length pairs.
                                      Can only be used with one input file.
     --output-replacements-xml      - Output replacements as XML.
     --qualifier-alignment=<string> - If set, overrides the qualifier alignment style
                                      determined by the QualifierAlignment style flag
     --sort-includes                - If set, overrides the include sorting behavior
                                      determined by the SortIncludes style flag
-    --style=<string>               - Coding style, currently supports:
-                                       LLVM, GNU, Google, Chromium, Microsoft, Mozilla, WebKit.
-                                     Use -style=file to load style configuration from
-                                     .clang-format file located in one of the parent
-                                     directories of the source file (or current
-                                     directory for stdin).
-                                     Use -style=file:<format_file_path> to explicitly specify
+    --style=<string>               - Set coding style. <string> can be:
+                                     1. A preset: LLVM, GNU, Google, Chromium, Microsoft,
+                                        Mozilla, WebKit.
+                                     2. 'file' to load style configuration from a
+                                        .clang-format file in one of the parent directories
+                                        of the source file (for stdin, see --assume-filename).
+                                        If no .clang-format file is found, falls back to
+                                        --fallback-style.
+                                        --style=file is the default.
+                                     3. 'file:<format_file_path>' to explicitly specify
                                         the configuration file.
-                                     Use -style="{key: value, ...}" to set specific
-                                     parameters, e.g.:
-                                       -style="{BasedOnStyle: llvm, IndentWidth: 8}"
+                                     4. "{key: value, ...}" to set specific parameters, e.g.:
+                                        --style="{BasedOnStyle: llvm, IndentWidth: 8}"
     --verbose                      - If set, shows the list of processed files
 
   Generic Options:
 
     --help                         - Display available options (--help-hidden for more)
     --help-list                    - Display list of available options (--help-list-hidden for more)
     --version                      - Display the version of this program
 

 
 
 Visual Studio Code Integration
 ==============================
 
 Get the latest Visual Studio Code extension from the `Visual Studio Marketplace <https://marketplace.visualstudio.com/items?itemName=xaver.clang-format>`_. The default key-binding is Alt-Shift-F.
 
 
 Script for patch reformatting
 =============================
 
 The python script `clang/tools/clang-format/clang-format-diff.py` parses the
 output of a unified diff and reformats all contained lines with
 :program:`clang-format`.
 
 .. code-block:: console
 
-  usage: clang-format-diff.py [-h] [-i] [-p NUM] [-regex PATTERN] [-style STYLE]
+  usage: clang-format-diff.py [-h] [-i] [-p NUM] [-regex PATTERN] [-iregex PATTERN] [-sort-includes] [-v] [-style STYLE]
+                              [-fallback-style FALLBACK_STYLE] [-binary BINARY]
 
-  Reformat changed lines in diff. Without -i option just output the diff that
-  would be introduced.
+  This script reads input from a unified diff and reformats all the changed
+  lines. This is useful to reformat all the lines touched by a specific patch.
+  Example usage for git/svn users:
+
+    git diff -U0 --no-color --relative HEAD^ | clang-format-diff.py -p1 -i
+    svn diff --diff-cmd=diff -x-U0 | clang-format-diff.py -i
+
+  It should be noted that the filename contained in the diff is used unmodified
+  to determine the source file to update. Users calling this script directly
+  should be careful to ensure that the path in the diff is correct relative to the
+  current working directory.
 
   optional arguments:
-    -h, --help      show this help message and exit
-    -i              apply edits to files instead of displaying a diff
-    -p NUM          strip the smallest prefix containing P slashes
-    -regex PATTERN  custom pattern selecting file paths to reformat
-    -style STYLE    formatting style to apply (LLVM, Google, Chromium, Mozilla,
-                    WebKit)
-
-So to reformat all the lines in the latest :program:`git` commit, just do:
-
-.. code-block:: console
+    -h, --help            show this help message and exit
+    -i                    apply edits to files instead of displaying a diff
+    -p NUM                strip the smallest prefix containing P slashes
+    -regex PATTERN        custom pattern selecting file paths to reformat (case sensitive, overrides -iregex)
+    -iregex PATTERN       custom pattern selecting file paths to reformat (case insensitive, overridden by -regex)
+    -sort-includes        let clang-format sort include blocks
+    -v, --verbose         be more verbose, ineffective without -i
+    -style STYLE          formatting style to apply (LLVM, GNU, Google, Chromium, Microsoft, Mozilla, WebKit)
+    -fallback-style FALLBACK_STYLE
+                          The name of the predefined style used as afallback in case clang-format is invoked with-style=file, but can not
+                          find the .clang-formatfile to use.
+    -binary BINARY        location of binary to use for clang-format
 
-  git diff -U0 --no-color HEAD^ | clang-format-diff.py -i -p1
-
-With Mercurial/:program:`hg`:
+To reformat all the lines in the latest Mercurial/:program:`hg` commit, do:
 
 .. code-block:: console
 
   hg diff -U0 --color=never | clang-format-diff.py -i -p1
 
-In an SVN client, you can do:
-
-.. code-block:: console
-
-  svn diff --diff-cmd=diff -x -U0 | clang-format-diff.py -i
-
 The option `-U0` will create a diff without context lines (the script would format
 those as well).
 
 These commands use the file paths shown in the diff output
 so they will only work from the root of the repository.
 
 Current State of Clang Format for LLVM
 ======================================
 
 The following table :doc:`ClangFormattedStatus` shows the current status of clang-formatting for the entire LLVM source tree.