[clang] c6eb5e3 - [docs][clang-format] Migrate generated clang-format docs to markdown (#211398)
via cfe-commits
cfe-commits at lists.llvm.org
Thu Aug 6 18:54:10 PDT 2026
Author: Reid Kleckner
Date: 2026-08-06T18:54:02-07:00
New Revision: c6eb5e390833295393e4d96c64adc67c4e3729b8
URL: https://github.com/llvm/llvm-project/commit/c6eb5e390833295393e4d96c64adc67c4e3729b8
DIFF: https://github.com/llvm/llvm-project/commit/c6eb5e390833295393e4d96c64adc67c4e3729b8.diff
LOG: [docs][clang-format] Migrate generated clang-format docs to markdown (#211398)
Tracking issue: #201242
See the [migration guide] for more information.
This is a stacked PR based on #211397 , which will be a standalone
commit that
renames *.rst -> *.md before this PR lands for history preservation
purposes.
[migration guide]:
https://llvm.org/docs/SphinxQuickstartTemplate.html#markdown-migration-guidelines
First, the generator was updated to generate markdown constructs, and
then the Doxygen comments in `Format.h` and `IncludeStyle.h` were also
modified to use markdown constructs. Mostly this means using single
backticks instead of double backticks, which is the Doxygen-native way
of expressing code font blocks anyway, so that's good.
To validate, I built the Sphinx docs and the doxygen, and I confirmed
that the generator script is idempotent, meaning it doesn't change the
markdown output. When I add a new option to clang-format, it shows up in
the help text block, so it works.
Added:
Modified:
clang/docs/ClangFormat.md
clang/docs/ClangFormatStyleOptions.md
clang/docs/tools/dump_format_help.py
clang/docs/tools/dump_format_style.py
clang/include/clang/Format/Format.h
clang/include/clang/Tooling/Inclusions/IncludeStyle.h
Removed:
################################################################################
diff --git a/clang/docs/ClangFormat.md b/clang/docs/ClangFormat.md
index 26490f9c15bb8..94fd51a3c1a0a 100644
--- a/clang/docs/ClangFormat.md
+++ b/clang/docs/ClangFormat.md
@@ -1,187 +1,179 @@
-===========
-ClangFormat
-===========
+# 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
+{doc}`LibFormat`. It can support your workflow in a variety of ways including a
standalone tool and editor integrations.
+## Standalone Tool
-Standalone Tool
-===============
-
-:program:`clang-format` is located in `clang/tools/clang-format` and can be used
+{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
- 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>] [<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
-
diff ering format depending on an option being
- supported or not.
- --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: .js .mjs .cjs .ts
- JSON: .json .ipynb
- Objective-C: .m .mm
- Proto: .proto .protodevel
- TableGen: .td
- TextProto: .txtpb .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.
- --fail-on-incomplete-format - If set, fail with exit code 1 on incomplete format.
- --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. 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=<filename> - A file containing a list of files to process, one per line.
- -i - Inplace edit <file>s, if specified.
- --length=<uint> - Format a range of this length (in bytes).
- Multiple ranges can be formatted by specifying
- several -offset and -length pairs.
- When only a single -offset is specified without
- -length, clang-format will format up to the end
- of the file.
- Can only be used with one input file.
- --lines=<string> - <start line>:<end line> - format a range of
- lines (both 1-based).
- Multiple ranges can be formatted by specifying
- several -lines arguments.
- Can't be used with -offset and -length.
- Can only be used with one input file.
- -n - Alias for --dry-run
- --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> - 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.
- 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
-
-
-.. END_FORMAT_HELP
+% START_FORMAT_HELP
+
+```console
+$ 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>] [<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
+
diff ering format depending on an option being
+ supported or not.
+ --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: .js .mjs .cjs .ts
+ JSON: .json .ipynb
+ Objective-C: .m .mm
+ Proto: .proto .protodevel
+ TableGen: .td
+ TextProto: .txtpb .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.
+ --fail-on-incomplete-format - If set, fail with exit code 1 on incomplete format.
+ --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. 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=<filename> - A file containing a list of files to process, one per line.
+ -i - Inplace edit <file>s, if specified.
+ --length=<uint> - Format a range of this length (in bytes).
+ Multiple ranges can be formatted by specifying
+ several -offset and -length pairs.
+ When only a single -offset is specified without
+ -length, clang-format will format up to the end
+ of the file.
+ Can only be used with one input file.
+ --lines=<string> - <start line>:<end line> - format a range of
+ lines (both 1-based).
+ Multiple ranges can be formatted by specifying
+ several -lines arguments.
+ Can't be used with -offset and -length.
+ Can only be used with one input file.
+ -n - Alias for --dry-run
+ --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> - 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.
+ 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
+```
+
+% END_FORMAT_HELP
When the desired code formatting style is
diff erent from the available options,
-the style can be customized using the ``-style="{key: value, ...}"`` option or
-by putting your style configuration in the ``.clang-format`` or ``_clang-format``
-file in your project's directory and using ``clang-format -style=file``.
-
-An easy way to create the ``.clang-format`` file is:
+the style can be customized using the `-style="{key: value, ...}"` option or
+by putting your style configuration in the `.clang-format` or `_clang-format`
+file in your project's directory and using `clang-format -style=file`.
-.. code-block:: console
+An easy way to create the `.clang-format` file is:
- clang-format -style=llvm -dump-config > .clang-format
+```console
+clang-format -style=llvm -dump-config > .clang-format
+```
-Available style options are described in :doc:`ClangFormatStyleOptions`.
+Available style options are described in {doc}`ClangFormatStyleOptions`.
-.clang-format-ignore
-====================
+## .clang-format-ignore
-You can create ``.clang-format-ignore`` files to make ``clang-format`` ignore
-certain files. A ``.clang-format-ignore`` file consists of patterns of file path
+You can create `.clang-format-ignore` files to make `clang-format` ignore
+certain files. A `.clang-format-ignore` file consists of patterns of file path
names. It has the following format:
-* A blank line is skipped.
-* Leading and trailing spaces of a line are trimmed.
-* A line starting with a hash (``#``) is a comment.
-* A non-comment line is a single pattern.
-* The slash (``/``) is used as the directory separator.
-* A pattern is relative to the directory of the ``.clang-format-ignore`` file
+- A blank line is skipped.
+- Leading and trailing spaces of a line are trimmed.
+- A line starting with a hash (`#`) is a comment.
+- A non-comment line is a single pattern.
+- The slash (`/`) is used as the directory separator.
+- A pattern is relative to the directory of the `.clang-format-ignore` file
(or the root directory if the pattern starts with a slash). Patterns
- containing drive names (e.g. ``C:``) are not supported.
-* Patterns follow the rules specified in `POSIX 2.13.1, 2.13.2, and Rule 1 of
- 2.13.3 <https://pubs.opengroup.org/onlinepubs/9699919799/utilities/
- V3_chap02.html#tag_18_13>`_.
-* Bash globstar (``**``) is supported.
-* A pattern is negated if it starts with a bang (``!``).
-
-To match all files in a directory, use e.g. ``foo/bar/*``. To match all files in
-the directory of the ``.clang-format-ignore`` file, use ``*``.
-Multiple ``.clang-format-ignore`` files are supported similar to the
-``.clang-format`` files, with a lower directory level file voiding the higher
+ containing drive names (e.g. `C:`) are not supported.
+- Patterns follow the rules specified in [POSIX 2.13.1, 2.13.2, and Rule 1 of
+ 2.13.3](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_13).
+- Bash globstar (`**`) is supported.
+- A pattern is negated if it starts with a bang (`!`).
+
+To match all files in a directory, use e.g. `foo/bar/*`. To match all files in
+the directory of the `.clang-format-ignore` file, use `*`.
+Multiple `.clang-format-ignore` files are supported similar to the
+`.clang-format` files, with a lower directory level file voiding the higher
level ones.
-Vim Integration
-===============
+## Vim Integration
-There is an integration for :program:`vim` which lets you run the
-:program:`clang-format` standalone tool on your current buffer, optionally
+There is an integration for {program}`vim` which lets you run the
+{program}`clang-format` standalone tool on your current buffer, optionally
selecting regions to reformat. The integration has the form of a `python`-file
which can be found under `clang/tools/clang-format/clang-format.py`.
This can be integrated by adding the following to your `.vimrc`:
-.. code-block:: vim
-
- if has('python')
- map <C-K> :pyf <path-to-this-file>/clang-format.py<cr>
- imap <C-K> <c-o>:pyf <path-to-this-file>/clang-format.py<cr>
- elseif has('python3')
- map <C-K> :py3f <path-to-this-file>/clang-format.py<cr>
- imap <C-K> <c-o>:py3f <path-to-this-file>/clang-format.py<cr>
- endif
-
-The first line enables :program:`clang-format` for NORMAL and VISUAL mode, the
+```vim
+if has('python')
+ map <C-K> :pyf <path-to-this-file>/clang-format.py<cr>
+ imap <C-K> <c-o>:pyf <path-to-this-file>/clang-format.py<cr>
+elseif has('python3')
+ map <C-K> :py3f <path-to-this-file>/clang-format.py<cr>
+ imap <C-K> <c-o>:py3f <path-to-this-file>/clang-format.py<cr>
+endif
+```
+
+The first line enables {program}`clang-format` for NORMAL and VISUAL mode, the
second line adds support for INSERT mode. Change "C-K" to another binding if
-you need :program:`clang-format` on a
diff erent key (C-K stands for Ctrl+k).
+you need {program}`clang-format` on a
diff erent key (C-K stands for Ctrl+k).
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
@@ -195,169 +187,158 @@ An alternative option is to format changes when saving a file and thus to
have a zero-effort integration into the coding workflow. To do this, add this to
your `.vimrc`:
-.. code-block:: vim
+```vim
+function! Formatonsave()
+ let l:format
diff = 1
+ pyf <path-to-this-file>/clang-format.py
+endfunction
+autocmd BufWritePre *.h,*.cc,*.cpp call Formatonsave()
+```
- function! Formatonsave()
- let l:format
diff = 1
- pyf <path-to-this-file>/clang-format.py
- endfunction
- autocmd BufWritePre *.h,*.cc,*.cpp call Formatonsave()
+## Emacs Integration
-
-Emacs Integration
-=================
-
-Similar to the integration for :program:`vim`, there is an integration for
-:program:`emacs`. It can be found at `clang/tools/clang-format/clang-format.el`
+Similar to the integration for {program}`vim`, there is an integration for
+{program}`emacs`. It can be found at `clang/tools/clang-format/clang-format.el`
and used by adding this to your `.emacs`:
-.. code-block:: common-lisp
-
- (load "<path-to-clang>/tools/clang-format/clang-format.el")
- (global-set-key [C-M-tab] 'clang-format-region)
+```common-lisp
+(load "<path-to-clang>/tools/clang-format/clang-format.el")
+(global-set-key [C-M-tab] 'clang-format-region)
+```
This binds the function `clang-format-region` to C-M-tab, which then formats the
current line or selected region.
+## BBEdit Integration
-BBEdit Integration
-==================
-
-:program:`clang-format` cannot be used as a text filter with BBEdit, but works
+{program}`clang-format` cannot be used as a text filter with BBEdit, but works
well via a script. The AppleScript to do this integration can be found at
`clang/tools/clang-format/clang-format-bbedit.applescript`; place a copy in
`~/Library/Application Support/BBEdit/Scripts`, and edit the path within it to
-point to your local copy of :program:`clang-format`.
+point to your local copy of {program}`clang-format`.
With this integration you can select the script from the Script menu and
-:program:`clang-format` will format the selection. Note that you can rename the
+{program}`clang-format` will format the selection. Note that you can rename the
menu item by renaming the script, and can assign the menu item a keyboard
shortcut in the BBEdit preferences, under Menus & Shortcuts.
+## CLion Integration
-CLion Integration
-=================
-
-:program:`clang-format` is integrated into `CLion <https://www.jetbrains
-.com/clion/>`_ as an alternative code formatter. CLion turns it on
-automatically when there is a ``.clang-format`` file under the project root.
-Code style rules are applied as you type, including indentation,
+{program}`clang-format` is integrated into
+[CLion](https://www.jetbrains.com/clion/) as an alternative code formatter.
+CLion turns it on automatically when there is a `.clang-format` file under the
+project root. Code style rules are applied as you type, including indentation,
auto-completion, code generation, and refactorings.
-:program:`clang-format` can also be enabled without a ``.clang-format`` file.
+{program}`clang-format` can also be enabled without a `.clang-format` file.
In this case, CLion prompts you to create one based on the current IDE settings
or the default LLVM style.
+## Visual Studio Integration
-Visual Studio Integration
-=========================
-
-Download the latest Visual Studio extension from the `alpha build site
-<https://llvm.org/builds/>`_. The default key-binding is Ctrl-R,Ctrl-F.
+Download the latest Visual Studio extension from the [alpha build
+site](https://llvm.org/builds/). The default key-binding is Ctrl-R,Ctrl-F.
+## Visual Studio Code Integration
-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.
-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.
-
-Git integration
-===============
+## Git integration
The script `clang/tools/clang-format/git-clang-format` can be used to
format just the lines touched in git commits:
-.. code-block:: console
-
- % git clang-format -h
- usage: git clang-format [OPTIONS] [<commit>] [<commit>|--staged] [--] [<file>...]
-
- If zero or one commits are given, run clang-format on all lines that
diff er
- between the working directory and <commit>, which defaults to HEAD. Changes are
- only applied to the working directory, or in the stage/index.
-
- Examples:
- To format staged changes, i.e everything that's been `git add`ed:
- git clang-format
-
- To also format everything touched in the most recent commit:
- git clang-format HEAD~1
-
- If you're on a branch off main, to format everything touched on your branch:
- git clang-format main
-
- If two commits are given (requires --
diff ), run clang-format on all lines in the
- second <commit> that
diff er from the first <commit>.
-
- The following git-config settings set the default of the corresponding option:
- clangFormat.binary
- clangFormat.commit
- clangFormat.extensions
- clangFormat.style
-
- positional arguments:
- <commit> revision from which to compute the
diff
- <file>... if specified, only consider
diff erences in these files
-
- optional arguments:
- -h, --help show this help message and exit
- --binary BINARY path to clang-format
- --commit COMMIT default commit to use if none is specified
- --
diff print a
diff instead of applying the changes
- --
diff stat print a
diff stat instead of applying the changes
- --extensions EXTENSIONS
- comma-separated list of file extensions to format, excluding the period and case-insensitive
- -f, --force allow changes to unstaged files
- -p, --patch select hunks interactively
- -q, --quiet print less information
- --staged, --cached format lines in the stage instead of the working dir
- --style STYLE passed to clang-format
- -v, --verbose print extra information
-
-
-Script for patch reformatting
-=============================
+```console
+% git clang-format -h
+usage: git clang-format [OPTIONS] [<commit>] [<commit>|--staged] [--] [<file>...]
+
+If zero or one commits are given, run clang-format on all lines that
diff er
+between the working directory and <commit>, which defaults to HEAD. Changes are
+only applied to the working directory, or in the stage/index.
+
+Examples:
+ To format staged changes, i.e everything that's been `git add`ed:
+ git clang-format
+
+ To also format everything touched in the most recent commit:
+ git clang-format HEAD~1
+
+ If you're on a branch off main, to format everything touched on your branch:
+ git clang-format main
+
+If two commits are given (requires --
diff ), run clang-format on all lines in the
+second <commit> that
diff er from the first <commit>.
+
+The following git-config settings set the default of the corresponding option:
+ clangFormat.binary
+ clangFormat.commit
+ clangFormat.extensions
+ clangFormat.style
+
+positional arguments:
+ <commit> revision from which to compute the
diff
+ <file>... if specified, only consider
diff erences in these files
+
+optional arguments:
+ -h, --help show this help message and exit
+ --binary BINARY path to clang-format
+ --commit COMMIT default commit to use if none is specified
+ --
diff print a
diff instead of applying the changes
+ --
diff stat print a
diff stat instead of applying the changes
+ --extensions EXTENSIONS
+ comma-separated list of file extensions to format, excluding the period and case-insensitive
+ -f, --force allow changes to unstaged files
+ -p, --patch select hunks interactively
+ -q, --quiet print less information
+ --staged, --cached format lines in the stage instead of the working dir
+ --style STYLE passed to clang-format
+ -v, --verbose print extra information
+```
+
+## 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] [-iregex PATTERN] [-sort-includes] [-v] [-style STYLE]
- [-fallback-style FALLBACK_STYLE] [-binary BINARY]
-
- 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 (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 a fallback 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
-
-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
+{program}`clang-format`.
+
+```console
+usage: clang-format-
diff .py [-h] [-i] [-p NUM] [-regex PATTERN] [-iregex PATTERN] [-sort-includes] [-v] [-style STYLE]
+ [-fallback-style FALLBACK_STYLE] [-binary BINARY]
+
+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 (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 a fallback 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
+```
+
+To reformat all the lines in the latest Mercurial/{program}`hg` commit, do:
+
+```console
+hg
diff -U0 --color=never | clang-format-
diff .py -i -p1
+```
The option `-U0` will create a
diff without context lines (the script would format
those as well).
diff --git a/clang/docs/ClangFormatStyleOptions.md b/clang/docs/ClangFormatStyleOptions.md
index e8cf2409e6c70..9b962e6e1e083 100644
--- a/clang/docs/ClangFormatStyleOptions.md
+++ b/clang/docs/ClangFormatStyleOptions.md
@@ -1,283 +1,268 @@
-..
- !!!!NOTE!!!!
- This file is automatically generated, in part. Do not edit the style options
- in this file directly. Instead, modify them in include/clang/Format/Format.h
- and run the docs/tools/dump_format_style.py script to update this file.
-
-.. raw:: html
-
- <style type="text/css">
- .versionbadge { background-color: #1c913d; height: 20px; display: inline-block; min-width: 120px; text-align: center; border-radius: 5px; color: #FFFFFF; font-family: "Verdana,Geneva,DejaVu Sans,sans-serif"; }
- </style>
-
+% !!!!NOTE!!!!
+% This file is automatically generated, in part. Do not edit the style options
+% in this file directly. Instead, modify them in include/clang/Format/Format.h
+% and run the docs/tools/dump_format_style.py script to update this file.
+
+```{raw} html
+<style type="text/css">
+ .versionbadge { background-color: #1c913d; height: 20px; display: inline-block; min-width: 120px; text-align: center; border-radius: 5px; color: #FFFFFF; font-family: "Verdana,Geneva,DejaVu Sans,sans-serif"; }
+</style>
+```
+
+```{eval-rst}
.. role:: versionbadge
+```
-==========================
-Clang-Format Style Options
-==========================
+# Clang-Format Style Options
-:doc:`ClangFormatStyleOptions` describes configurable formatting style options
-supported by :doc:`LibFormat` and :doc:`ClangFormat`.
+{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
+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, Microsoft) or
create a custom style by configuring specific style options.
+## Configuring Style with clang-format
-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`` or
-``_clang-format`` file in the project directory.
+{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` or
+`_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
+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.
-When using ``-style=file:<format_file_path>``, :program:`clang-format` for
+When using `-style=file:<format_file_path>`, {program}`clang-format` for
each input file will use the format file located at `<format_file_path>`.
The path may be absolute or relative to the working directory.
-The ``.clang-format`` file uses YAML format:
+The `.clang-format` file uses YAML format:
-.. code-block:: yaml
-
- key1: value1
- key2: value2
- # A comment.
- ...
+```yaml
+key1: value1
+key2: value2
+# A comment.
+...
+```
The configuration file can consist of several sections each having
diff erent
-``Language:`` parameter denoting the programming language this section of the
+`Language:` parameter denoting the programming language this section of the
configuration is targeted at. See the description of the **Language** option
below for the list of supported languages. The first section may have no
language set, it will set the default style options for all languages.
Configuration sections for specific language will override options set in the
default section.
-When :program:`clang-format` formats a file, it auto-detects the language using
+When {program}`clang-format` formats a file, it auto-detects the language using
the file name. When formatting standard input or a file that doesn't have the
-extension corresponding to its language, ``-assume-filename=`` option can be
-used to override the file name :program:`clang-format` uses to detect the
+extension corresponding to its language, `-assume-filename=` option can be
+used to override the file name {program}`clang-format` uses to detect the
language.
An example of a configuration file for multiple languages:
-.. code-block:: yaml
-
- ---
- # We'll use defaults from the LLVM style, but with 4 columns indentation.
- BasedOnStyle: LLVM
- IndentWidth: 4
- ---
- Language: Cpp
- # Force pointers to the type for C++.
- DerivePointerAlignment: false
- PointerAlignment: Left
- ---
- Language: JavaScript
- # Use 100 columns for JS.
- ColumnLimit: 100
- ---
- Language: Proto
- # Don't format .proto files.
- DisableFormat: true
- ---
- Language: CSharp
- # Use 100 columns for C#.
- ColumnLimit: 100
- ...
-
-An easy way to get a valid ``.clang-format`` file containing all configuration
+```yaml
+---
+# We'll use defaults from the LLVM style, but with 4 columns indentation.
+BasedOnStyle: LLVM
+IndentWidth: 4
+---
+Language: Cpp
+# Force pointers to the type for C++.
+DerivePointerAlignment: false
+PointerAlignment: Left
+---
+Language: JavaScript
+# Use 100 columns for JS.
+ColumnLimit: 100
+---
+Language: Proto
+# Don't format .proto files.
+DisableFormat: true
+---
+Language: CSharp
+# Use 100 columns for C#.
+ColumnLimit: 100
+...
+```
+
+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
+```console
+clang-format -style=llvm -dump-config > .clang-format
+```
-When specifying configuration in the ``-style=`` option, the same configuration
+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, ...}'
-
+```console
+-style='{key1: value1, key2: value2, ...}'
+```
-Disabling Formatting on a Piece of Code
-=======================================
+## Disabling Formatting on a Piece of Code
Clang-format understands also special comments that switch formatting in a
-delimited range. The code between a comment ``// clang-format off`` or
-``/* clang-format off */`` up to a comment ``// clang-format on`` or
-``/* clang-format on */`` will not be formatted. The comments themselves will be
-formatted (aligned) normally. Also, a colon (``:``) and additional text may
-follow ``// clang-format off`` or ``// clang-format on`` to explain why
+delimited range. The code between a comment `// clang-format off` or
+`/* clang-format off */` up to a comment `// clang-format on` or
+`/* clang-format on */` will not be formatted. The comments themselves will be
+formatted (aligned) normally. Also, a colon (`:`) and additional text may
+follow `// clang-format off` or `// clang-format on` to explain why
clang-format is turned off or back on.
-.. code-block:: c++
+```c++
+int formatted_code;
+// clang-format off
+ void unformatted_code ;
+// clang-format on
+void formatted_code_again;
+```
- int formatted_code;
- // clang-format off
- void unformatted_code ;
- // clang-format on
- void formatted_code_again;
-
-In addition, the ``OneLineFormatOffRegex`` option gives you a concise way to
+In addition, the `OneLineFormatOffRegex` option gives you a concise way to
disable formatting for all of the lines that match the regular expression.
+## Configuring Style in Code
-Configuring Style in Code
-=========================
-
-When using ``clang::format::reformat(...)`` functions, the format is specified
-by supplying the `clang::format::FormatStyle
-<https://clang.llvm.org/doxygen/structclang_1_1format_1_1FormatStyle.html>`_
+When using `clang::format::reformat(...)` functions, the format is specified
+by supplying the [clang::format::FormatStyle](https://clang.llvm.org/doxygen/structclang_1_1format_1_1FormatStyle.html)
structure.
-
-Configurable Format Style Options
-=================================
+## 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: ``Auto``).
+enumeration member (with a prefix, e.g. `LS_Auto`), and as a value usable in
+the configuration (without a prefix: `Auto`).
+
+(basedonstyle)=
-.. _BasedOnStyle:
+**BasedOnStyle** (`String`) {ref}`¶ <BasedOnStyle>`
-**BasedOnStyle** (``String``) :ref:`¶ <BasedOnStyle>`
- The style used for all options not specifically set in the configuration.
+: 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).
+ 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
- <https://llvm.org/docs/CodingStandards.html>`_
- * ``Google``
- A style complying with `Google's C++ style guide
- <https://google.github.io/styleguide/cppguide.html>`_
- * ``Chromium``
- A style complying with `Chromium's style guide
- <https://chromium.googlesource.com/chromium/src/+/refs/heads/main/styleguide/styleguide.md>`_
- * ``Mozilla``
- A style complying with `Mozilla's style guide
- <https://firefox-source-docs.mozilla.org/code-quality/coding-style/index.html>`_
- * ``WebKit``
- A style complying with `WebKit's style guide
- <https://www.webkit.org/coding/coding-style.html>`_
- * ``Microsoft``
- A style complying with `Microsoft's style guide
- <https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-code-style-settings-reference>`_
- * ``GNU``
- A style complying with the `GNU coding standards
- <https://www.gnu.org/prep/standards/standards.html>`_
- * ``InheritParentConfig``
- Not a real style, but allows to use the ``.clang-format`` file from the
+ - `LLVM`
+ A style complying with the [LLVM coding standards](https://llvm.org/docs/CodingStandards.html)
+ - `Google`
+ A style complying with [Google's C++ style guide](https://google.github.io/styleguide/cppguide.html)
+ - `Chromium`
+ A style complying with [Chromium's style guide](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/styleguide/styleguide.md)
+ - `Mozilla`
+ A style complying with [Mozilla's style guide](https://firefox-source-docs.mozilla.org/code-quality/coding-style/index.html)
+ - `WebKit`
+ A style complying with [WebKit's style guide](https://www.webkit.org/coding/coding-style.html)
+ - `Microsoft`
+ A style complying with [Microsoft's style guide](https://docs.microsoft.com/en-us/visualstudio/ide/editorconfig-code-style-settings-reference)
+ - `GNU`
+ A style complying with the [GNU coding standards](https://www.gnu.org/prep/standards/standards.html)
+ - `InheritParentConfig`
+ Not a real style, but allows to use the `.clang-format` file from the
parent directory (or its parent if there is none). If there is no parent
- file found it falls back to the ``fallback`` style, and applies the changes
+ file found it falls back to the `fallback` style, and applies the changes
to that. With this option you can overwrite some parts of your main style
for your subdirectories. This is also possible through the command line,
e.g.:
- ``--style={BasedOnStyle: InheritParentConfig, ColumnLimit: 20}``
- * ``InheritParentConfig=<directory-path>``
+ `--style={BasedOnStyle: InheritParentConfig, ColumnLimit: 20}`
+ - `InheritParentConfig=<directory-path>`
Same as the above except that the inheritance is redirected to
- ``<directory-path>``. This is only supported in configuration files.
+ `<directory-path>`. This is only supported in configuration files.
-.. START_FORMAT_STYLE_OPTIONS
+% START_FORMAT_STYLE_OPTIONS
-.. _AccessModifierOffset:
+(accessmodifieroffset)=
-**AccessModifierOffset** (``Integer``) :versionbadge:`clang-format 3.3` :ref:`¶ <AccessModifierOffset>`
- The extra indent or outdent of access modifiers, e.g. ``public:``.
+**AccessModifierOffset** (`Integer`) {versionbadge}`clang-format 3.3` {ref}`¶ <AccessModifierOffset>`
-.. _AlignAfterOpenBracket:
+: The extra indent or outdent of access modifiers, e.g. `public:`.
-**AlignAfterOpenBracket** (``Boolean``) :versionbadge:`clang-format 3.8` :ref:`¶ <AlignAfterOpenBracket>`
- If ``true``, horizontally aligns arguments after an open bracket.
+(alignafteropenbracket)=
+**AlignAfterOpenBracket** (`Boolean`) {versionbadge}`clang-format 3.8` {ref}`¶ <AlignAfterOpenBracket>`
- .. code-block:: c++
+: If `true`, horizontally aligns arguments after an open bracket.
- true: vs. false
- someLongFunction(argument1, someLongFunction(argument1,
- argument2); argument2);
+ ```c++
+ true: vs. false
+ someLongFunction(argument1, someLongFunction(argument1,
+ argument2); argument2);
+ ```
-
- .. note::
-
- As of clang-format 22 this option is a bool with the previous
- option of ``Align`` replaced with ``true``, ``DontAlign`` replaced
- with ``false``, and the options of ``AlwaysBreak`` and ``BlockIndent``
- replaced with ``true`` and with setting of new style options using
- ``BreakAfterOpenBracketBracedList``, ``BreakAfterOpenBracketFunction``,
- ``BreakAfterOpenBracketIf``, ``BreakBeforeCloseBracketBracedList``,
- ``BreakBeforeCloseBracketFunction``, and ``BreakBeforeCloseBracketIf``.
+ :::{note}
+ As of clang-format 22 this option is a bool with the previous
+ option of `Align` replaced with `true`, `DontAlign` replaced
+ with `false`, and the options of `AlwaysBreak` and `BlockIndent`
+ replaced with `true` and with setting of new style options using
+ `BreakAfterOpenBracketBracedList`, `BreakAfterOpenBracketFunction`,
+ `BreakAfterOpenBracketIf`, `BreakBeforeCloseBracketBracedList`,
+ `BreakBeforeCloseBracketFunction`, and `BreakBeforeCloseBracketIf`.
+ :::
This applies to round brackets (parentheses), angle brackets and square
brackets.
-.. _AlignArrayOfStructures:
-
-**AlignArrayOfStructures** (``ArrayInitializerAlignmentStyle``) :versionbadge:`clang-format 13` :ref:`¶ <AlignArrayOfStructures>`
- If not ``None``, when using initialization for an array of structs
- aligns the fields into columns.
+(alignarrayofstructures)=
+**AlignArrayOfStructures** (`ArrayInitializerAlignmentStyle`) {versionbadge}`clang-format 13` {ref}`¶ <AlignArrayOfStructures>`
- .. note::
+: If not `None`, when using initialization for an array of structs
+ aligns the fields into columns.
- As of clang-format 15 this option only applied to arrays with equal
- number of columns per row.
+ :::{note}
+ As of clang-format 15 this option only applied to arrays with equal
+ number of columns per row.
+ :::
Possible values:
- * ``AIAS_Left`` (in configuration: ``Left``)
+ - `AIAS_Left` (in configuration: `Left`)
Align array column and left justify the columns e.g.:
- .. code-block:: c++
-
- struct test demo[] =
- {
- {56, 23, "hello"},
- {-1, 93463, "world"},
- {7, 5, "!!" }
- };
+ ```c++
+ struct test demo[] =
+ {
+ {56, 23, "hello"},
+ {-1, 93463, "world"},
+ {7, 5, "!!" }
+ };
+ ```
- * ``AIAS_Right`` (in configuration: ``Right``)
+ - `AIAS_Right` (in configuration: `Right`)
Align array column and right justify the columns e.g.:
- .. code-block:: c++
-
- struct test demo[] =
- {
- {56, 23, "hello"},
- {-1, 93463, "world"},
- { 7, 5, "!!"}
- };
+ ```c++
+ struct test demo[] =
+ {
+ {56, 23, "hello"},
+ {-1, 93463, "world"},
+ { 7, 5, "!!"}
+ };
+ ```
- * ``AIAS_None`` (in configuration: ``None``)
+ - `AIAS_None` (in configuration: `None`)
Don't align array initializer columns.
-.. _AlignConsecutiveAssignments:
+(alignconsecutiveassignments)=
-**AlignConsecutiveAssignments** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 3.8` :ref:`¶ <AlignConsecutiveAssignments>`
- Style of aligning consecutive assignments.
+**AlignConsecutiveAssignments** (`AlignConsecutiveStyle`) {versionbadge}`clang-format 3.8` {ref}`¶ <AlignConsecutiveAssignments>`
- ``Consecutive`` will result in formattings like:
+: Style of aligning consecutive assignments.
- .. code-block:: c++
+ `Consecutive` will result in formattings like:
- int a = 1;
- int somelongname = 2;
- double c = 3;
+ ```c++
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
+ ```
Nested configuration flags:
@@ -285,162 +270,163 @@ the configuration (without a prefix: ``Auto``).
They can also be read as a whole for compatibility. The choices are:
- * ``None``
- * ``Consecutive``
- * ``AcrossEmptyLines``
- * ``AcrossComments``
- * ``AcrossEmptyLinesAndComments``
+ - `None`
+ - `Consecutive`
+ - `AcrossEmptyLines`
+ - `AcrossComments`
+ - `AcrossEmptyLinesAndComments`
For example, to align across empty lines and not across comments, either
of these work.
- .. code-block:: c++
-
- AlignConsecutiveAssignments: AcrossEmptyLines
-
- AlignConsecutiveAssignments:
- Enabled: true
- AcrossEmptyLines: true
- AcrossComments: false
-
- * ``bool Enabled`` Whether aligning is enabled.
-
- .. code-block:: c++
+ ```c++
+ AlignConsecutiveAssignments: AcrossEmptyLines
- #define SHORT_NAME 42
- #define LONGER_NAME 0x007f
- #define EVEN_LONGER_NAME (2)
- #define foo(x) (x * x)
- #define bar(y, z) (y + z)
+ AlignConsecutiveAssignments:
+ Enabled: true
+ AcrossEmptyLines: true
+ AcrossComments: false
+ ```
- int a = 1;
- int somelongname = 2;
- double c = 3;
+ - `bool Enabled` Whether aligning is enabled.
- int aaaa : 1;
- int b : 12;
- int ccc : 8;
-
- int aaaa = 12;
- float b = 23;
- std::string ccc;
+ ```c++
+ #define SHORT_NAME 42
+ #define LONGER_NAME 0x007f
+ #define EVEN_LONGER_NAME (2)
+ #define foo(x) (x * x)
+ #define bar(y, z) (y + z)
- * ``bool AcrossEmptyLines`` Whether to align across empty lines.
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- .. code-block:: c++
+ int aaaa : 1;
+ int b : 12;
+ int ccc : 8;
- true:
- int a = 1;
- int somelongname = 2;
- double c = 3;
+ int aaaa = 12;
+ float b = 23;
+ std::string ccc;
+ ```
- int d = 3;
+ - `bool AcrossEmptyLines` Whether to align across empty lines.
- false:
- int a = 1;
- int somelongname = 2;
- double c = 3;
+ ```c++
+ true:
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- int d = 3;
+ int d = 3;
- * ``bool AcrossComments`` Whether to align across comments.
+ false:
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- .. code-block:: c++
+ int d = 3;
+ ```
- true:
- int d = 3;
- /* A comment. */
- double e = 4;
+ - `bool AcrossComments` Whether to align across comments.
- false:
- int d = 3;
- /* A comment. */
- double e = 4;
+ ```c++
+ true:
+ int d = 3;
+ /* A comment. */
+ double e = 4;
- * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments
- like ``+=`` are aligned along with ``=``.
+ false:
+ int d = 3;
+ /* A comment. */
+ double e = 4;
+ ```
- .. code-block:: c++
+ - `bool AlignCompound` Only for `AlignConsecutiveAssignments`. Whether compound assignments
+ like `+=` are aligned along with `=`.
- true:
- a &= 2;
- bbb = 2;
+ ```c++
+ true:
+ a &= 2;
+ bbb = 2;
- false:
- a &= 2;
- bbb = 2;
+ false:
+ a &= 2;
+ bbb = 2;
+ ```
- * ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations
+ - `bool AlignFunctionDeclarations` Only for `AlignConsecutiveDeclarations`. Whether function declarations
are aligned.
- .. code-block:: c++
-
- true:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
+ ```c++
+ true:
+ unsigned int f1(void);
+ void f2(void);
+ size_t f3(void);
- false:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
+ false:
+ unsigned int f1(void);
+ void f2(void);
+ size_t f3(void);
+ ```
- * ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are
+ - `bool AlignFunctionPointers` Only for `AlignConsecutiveDeclarations`. Whether function pointers are
aligned.
- .. code-block:: c++
-
- true:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- false:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- * ``bool EnumAssignments`` Only for ``AlignConsecutiveAssignments``.
- Whether enum assignments are aligned. If ``Enabled`` is ``false``,
- setting this to ``true`` forces alignment for enum assignments only.
- If ``Enabled`` is ``true``, enum assignments are always aligned.
+ ```c++
+ true:
+ unsigned i;
+ int &r;
+ int *p;
+ int (*f)();
- * ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment
+ false:
+ unsigned i;
+ int &r;
+ int *p;
+ int (*f)();
+ ```
+
+ - `bool EnumAssignments` Only for `AlignConsecutiveAssignments`.
+ Whether enum assignments are aligned. If `Enabled` is `false`,
+ setting this to `true` forces alignment for enum assignments only.
+ If `Enabled` is `true`, enum assignments are always aligned.
+
+ - `bool PadOperators` Only for `AlignConsecutiveAssignments`. Whether short assignment
operators are left-padded to the same length as long ones in order to
put all assignment operators to the right of the left hand side.
- .. code-block:: c++
+ ```c++
+ true:
+ a >>= 2;
+ bbb = 2;
- true:
- a >>= 2;
- bbb = 2;
+ a = 2;
+ bbb >>= 2;
- a = 2;
- bbb >>= 2;
+ false:
+ a >>= 2;
+ bbb = 2;
- false:
- a >>= 2;
- bbb = 2;
+ a = 2;
+ bbb >>= 2;
+ ```
- a = 2;
- bbb >>= 2;
+(alignconsecutivebitfields)=
-.. _AlignConsecutiveBitFields:
+**AlignConsecutiveBitFields** (`AlignConsecutiveStyle`) {versionbadge}`clang-format 11` {ref}`¶ <AlignConsecutiveBitFields>`
-**AlignConsecutiveBitFields** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 11` :ref:`¶ <AlignConsecutiveBitFields>`
- Style of aligning consecutive bit fields.
+: Style of aligning consecutive bit fields.
- ``Consecutive`` will align the bitfield separators of consecutive lines.
+ `Consecutive` will align the bitfield separators of consecutive lines.
This will result in formattings like:
- .. code-block:: c++
-
- int aaaa : 1;
- int b : 12;
- int ccc : 8;
+ ```c++
+ int aaaa : 1;
+ int b : 12;
+ int ccc : 8;
+ ```
Nested configuration flags:
@@ -448,162 +434,163 @@ the configuration (without a prefix: ``Auto``).
They can also be read as a whole for compatibility. The choices are:
- * ``None``
- * ``Consecutive``
- * ``AcrossEmptyLines``
- * ``AcrossComments``
- * ``AcrossEmptyLinesAndComments``
+ - `None`
+ - `Consecutive`
+ - `AcrossEmptyLines`
+ - `AcrossComments`
+ - `AcrossEmptyLinesAndComments`
For example, to align across empty lines and not across comments, either
of these work.
- .. code-block:: c++
-
- AlignConsecutiveBitFields: AcrossEmptyLines
-
- AlignConsecutiveBitFields:
- Enabled: true
- AcrossEmptyLines: true
- AcrossComments: false
-
- * ``bool Enabled`` Whether aligning is enabled.
+ ```c++
+ AlignConsecutiveBitFields: AcrossEmptyLines
- .. code-block:: c++
+ AlignConsecutiveBitFields:
+ Enabled: true
+ AcrossEmptyLines: true
+ AcrossComments: false
+ ```
- #define SHORT_NAME 42
- #define LONGER_NAME 0x007f
- #define EVEN_LONGER_NAME (2)
- #define foo(x) (x * x)
- #define bar(y, z) (y + z)
+ - `bool Enabled` Whether aligning is enabled.
- int a = 1;
- int somelongname = 2;
- double c = 3;
-
- int aaaa : 1;
- int b : 12;
- int ccc : 8;
-
- int aaaa = 12;
- float b = 23;
- std::string ccc;
+ ```c++
+ #define SHORT_NAME 42
+ #define LONGER_NAME 0x007f
+ #define EVEN_LONGER_NAME (2)
+ #define foo(x) (x * x)
+ #define bar(y, z) (y + z)
- * ``bool AcrossEmptyLines`` Whether to align across empty lines.
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- .. code-block:: c++
+ int aaaa : 1;
+ int b : 12;
+ int ccc : 8;
- true:
- int a = 1;
- int somelongname = 2;
- double c = 3;
+ int aaaa = 12;
+ float b = 23;
+ std::string ccc;
+ ```
- int d = 3;
+ - `bool AcrossEmptyLines` Whether to align across empty lines.
- false:
- int a = 1;
- int somelongname = 2;
- double c = 3;
+ ```c++
+ true:
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- int d = 3;
+ int d = 3;
- * ``bool AcrossComments`` Whether to align across comments.
+ false:
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- .. code-block:: c++
+ int d = 3;
+ ```
- true:
- int d = 3;
- /* A comment. */
- double e = 4;
+ - `bool AcrossComments` Whether to align across comments.
- false:
- int d = 3;
- /* A comment. */
- double e = 4;
+ ```c++
+ true:
+ int d = 3;
+ /* A comment. */
+ double e = 4;
- * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments
- like ``+=`` are aligned along with ``=``.
+ false:
+ int d = 3;
+ /* A comment. */
+ double e = 4;
+ ```
- .. code-block:: c++
+ - `bool AlignCompound` Only for `AlignConsecutiveAssignments`. Whether compound assignments
+ like `+=` are aligned along with `=`.
- true:
- a &= 2;
- bbb = 2;
+ ```c++
+ true:
+ a &= 2;
+ bbb = 2;
- false:
- a &= 2;
- bbb = 2;
+ false:
+ a &= 2;
+ bbb = 2;
+ ```
- * ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations
+ - `bool AlignFunctionDeclarations` Only for `AlignConsecutiveDeclarations`. Whether function declarations
are aligned.
- .. code-block:: c++
-
- true:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
+ ```c++
+ true:
+ unsigned int f1(void);
+ void f2(void);
+ size_t f3(void);
- false:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
+ false:
+ unsigned int f1(void);
+ void f2(void);
+ size_t f3(void);
+ ```
- * ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are
+ - `bool AlignFunctionPointers` Only for `AlignConsecutiveDeclarations`. Whether function pointers are
aligned.
- .. code-block:: c++
-
- true:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- false:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- * ``bool EnumAssignments`` Only for ``AlignConsecutiveAssignments``.
- Whether enum assignments are aligned. If ``Enabled`` is ``false``,
- setting this to ``true`` forces alignment for enum assignments only.
- If ``Enabled`` is ``true``, enum assignments are always aligned.
+ ```c++
+ true:
+ unsigned i;
+ int &r;
+ int *p;
+ int (*f)();
- * ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment
+ false:
+ unsigned i;
+ int &r;
+ int *p;
+ int (*f)();
+ ```
+
+ - `bool EnumAssignments` Only for `AlignConsecutiveAssignments`.
+ Whether enum assignments are aligned. If `Enabled` is `false`,
+ setting this to `true` forces alignment for enum assignments only.
+ If `Enabled` is `true`, enum assignments are always aligned.
+
+ - `bool PadOperators` Only for `AlignConsecutiveAssignments`. Whether short assignment
operators are left-padded to the same length as long ones in order to
put all assignment operators to the right of the left hand side.
- .. code-block:: c++
+ ```c++
+ true:
+ a >>= 2;
+ bbb = 2;
- true:
- a >>= 2;
- bbb = 2;
+ a = 2;
+ bbb >>= 2;
- a = 2;
- bbb >>= 2;
+ false:
+ a >>= 2;
+ bbb = 2;
- false:
- a >>= 2;
- bbb = 2;
+ a = 2;
+ bbb >>= 2;
+ ```
- a = 2;
- bbb >>= 2;
+(alignconsecutivedeclarations)=
-.. _AlignConsecutiveDeclarations:
+**AlignConsecutiveDeclarations** (`AlignConsecutiveStyle`) {versionbadge}`clang-format 3.8` {ref}`¶ <AlignConsecutiveDeclarations>`
-**AlignConsecutiveDeclarations** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 3.8` :ref:`¶ <AlignConsecutiveDeclarations>`
- Style of aligning consecutive declarations.
+: Style of aligning consecutive declarations.
- ``Consecutive`` will align the declaration names of consecutive lines.
+ `Consecutive` will align the declaration names of consecutive lines.
This will result in formattings like:
- .. code-block:: c++
-
- int aaaa = 12;
- float b = 23;
- std::string ccc;
+ ```c++
+ int aaaa = 12;
+ float b = 23;
+ std::string ccc;
+ ```
Nested configuration flags:
@@ -611,163 +598,164 @@ the configuration (without a prefix: ``Auto``).
They can also be read as a whole for compatibility. The choices are:
- * ``None``
- * ``Consecutive``
- * ``AcrossEmptyLines``
- * ``AcrossComments``
- * ``AcrossEmptyLinesAndComments``
+ - `None`
+ - `Consecutive`
+ - `AcrossEmptyLines`
+ - `AcrossComments`
+ - `AcrossEmptyLinesAndComments`
For example, to align across empty lines and not across comments, either
of these work.
- .. code-block:: c++
-
- AlignConsecutiveDeclarations: AcrossEmptyLines
-
- AlignConsecutiveDeclarations:
- Enabled: true
- AcrossEmptyLines: true
- AcrossComments: false
+ ```c++
+ AlignConsecutiveDeclarations: AcrossEmptyLines
- * ``bool Enabled`` Whether aligning is enabled.
+ AlignConsecutiveDeclarations:
+ Enabled: true
+ AcrossEmptyLines: true
+ AcrossComments: false
+ ```
- .. code-block:: c++
+ - `bool Enabled` Whether aligning is enabled.
- #define SHORT_NAME 42
- #define LONGER_NAME 0x007f
- #define EVEN_LONGER_NAME (2)
- #define foo(x) (x * x)
- #define bar(y, z) (y + z)
-
- int a = 1;
- int somelongname = 2;
- double c = 3;
-
- int aaaa : 1;
- int b : 12;
- int ccc : 8;
-
- int aaaa = 12;
- float b = 23;
- std::string ccc;
+ ```c++
+ #define SHORT_NAME 42
+ #define LONGER_NAME 0x007f
+ #define EVEN_LONGER_NAME (2)
+ #define foo(x) (x * x)
+ #define bar(y, z) (y + z)
- * ``bool AcrossEmptyLines`` Whether to align across empty lines.
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- .. code-block:: c++
+ int aaaa : 1;
+ int b : 12;
+ int ccc : 8;
- true:
- int a = 1;
- int somelongname = 2;
- double c = 3;
+ int aaaa = 12;
+ float b = 23;
+ std::string ccc;
+ ```
- int d = 3;
+ - `bool AcrossEmptyLines` Whether to align across empty lines.
- false:
- int a = 1;
- int somelongname = 2;
- double c = 3;
+ ```c++
+ true:
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- int d = 3;
+ int d = 3;
- * ``bool AcrossComments`` Whether to align across comments.
+ false:
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- .. code-block:: c++
+ int d = 3;
+ ```
- true:
- int d = 3;
- /* A comment. */
- double e = 4;
+ - `bool AcrossComments` Whether to align across comments.
- false:
- int d = 3;
- /* A comment. */
- double e = 4;
+ ```c++
+ true:
+ int d = 3;
+ /* A comment. */
+ double e = 4;
- * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments
- like ``+=`` are aligned along with ``=``.
+ false:
+ int d = 3;
+ /* A comment. */
+ double e = 4;
+ ```
- .. code-block:: c++
+ - `bool AlignCompound` Only for `AlignConsecutiveAssignments`. Whether compound assignments
+ like `+=` are aligned along with `=`.
- true:
- a &= 2;
- bbb = 2;
+ ```c++
+ true:
+ a &= 2;
+ bbb = 2;
- false:
- a &= 2;
- bbb = 2;
+ false:
+ a &= 2;
+ bbb = 2;
+ ```
- * ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations
+ - `bool AlignFunctionDeclarations` Only for `AlignConsecutiveDeclarations`. Whether function declarations
are aligned.
- .. code-block:: c++
-
- true:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
+ ```c++
+ true:
+ unsigned int f1(void);
+ void f2(void);
+ size_t f3(void);
- false:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
+ false:
+ unsigned int f1(void);
+ void f2(void);
+ size_t f3(void);
+ ```
- * ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are
+ - `bool AlignFunctionPointers` Only for `AlignConsecutiveDeclarations`. Whether function pointers are
aligned.
- .. code-block:: c++
-
- true:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- false:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- * ``bool EnumAssignments`` Only for ``AlignConsecutiveAssignments``.
- Whether enum assignments are aligned. If ``Enabled`` is ``false``,
- setting this to ``true`` forces alignment for enum assignments only.
- If ``Enabled`` is ``true``, enum assignments are always aligned.
+ ```c++
+ true:
+ unsigned i;
+ int &r;
+ int *p;
+ int (*f)();
- * ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment
+ false:
+ unsigned i;
+ int &r;
+ int *p;
+ int (*f)();
+ ```
+
+ - `bool EnumAssignments` Only for `AlignConsecutiveAssignments`.
+ Whether enum assignments are aligned. If `Enabled` is `false`,
+ setting this to `true` forces alignment for enum assignments only.
+ If `Enabled` is `true`, enum assignments are always aligned.
+
+ - `bool PadOperators` Only for `AlignConsecutiveAssignments`. Whether short assignment
operators are left-padded to the same length as long ones in order to
put all assignment operators to the right of the left hand side.
- .. code-block:: c++
-
- true:
- a >>= 2;
- bbb = 2;
+ ```c++
+ true:
+ a >>= 2;
+ bbb = 2;
- a = 2;
- bbb >>= 2;
+ a = 2;
+ bbb >>= 2;
- false:
- a >>= 2;
- bbb = 2;
+ false:
+ a >>= 2;
+ bbb = 2;
- a = 2;
- bbb >>= 2;
+ a = 2;
+ bbb >>= 2;
+ ```
-.. _AlignConsecutiveMacros:
+(alignconsecutivemacros)=
-**AlignConsecutiveMacros** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 9` :ref:`¶ <AlignConsecutiveMacros>`
- Style of aligning consecutive macro definitions.
+**AlignConsecutiveMacros** (`AlignConsecutiveStyle`) {versionbadge}`clang-format 9` {ref}`¶ <AlignConsecutiveMacros>`
- ``Consecutive`` will result in formattings like:
+: Style of aligning consecutive macro definitions.
- .. code-block:: c++
+ `Consecutive` will result in formattings like:
- #define SHORT_NAME 42
- #define LONGER_NAME 0x007f
- #define EVEN_LONGER_NAME (2)
- #define foo(x) (x * x)
- #define bar(y, z) (y + z)
+ ```c++
+ #define SHORT_NAME 42
+ #define LONGER_NAME 0x007f
+ #define EVEN_LONGER_NAME (2)
+ #define foo(x) (x * x)
+ #define bar(y, z) (y + z)
+ ```
Nested configuration flags:
@@ -775,282 +763,283 @@ the configuration (without a prefix: ``Auto``).
They can also be read as a whole for compatibility. The choices are:
- * ``None``
- * ``Consecutive``
- * ``AcrossEmptyLines``
- * ``AcrossComments``
- * ``AcrossEmptyLinesAndComments``
+ - `None`
+ - `Consecutive`
+ - `AcrossEmptyLines`
+ - `AcrossComments`
+ - `AcrossEmptyLinesAndComments`
For example, to align across empty lines and not across comments, either
of these work.
- .. code-block:: c++
-
- AlignConsecutiveMacros: AcrossEmptyLines
-
- AlignConsecutiveMacros:
- Enabled: true
- AcrossEmptyLines: true
- AcrossComments: false
-
- * ``bool Enabled`` Whether aligning is enabled.
+ ```c++
+ AlignConsecutiveMacros: AcrossEmptyLines
- .. code-block:: c++
+ AlignConsecutiveMacros:
+ Enabled: true
+ AcrossEmptyLines: true
+ AcrossComments: false
+ ```
- #define SHORT_NAME 42
- #define LONGER_NAME 0x007f
- #define EVEN_LONGER_NAME (2)
- #define foo(x) (x * x)
- #define bar(y, z) (y + z)
+ - `bool Enabled` Whether aligning is enabled.
- int a = 1;
- int somelongname = 2;
- double c = 3;
-
- int aaaa : 1;
- int b : 12;
- int ccc : 8;
-
- int aaaa = 12;
- float b = 23;
- std::string ccc;
+ ```c++
+ #define SHORT_NAME 42
+ #define LONGER_NAME 0x007f
+ #define EVEN_LONGER_NAME (2)
+ #define foo(x) (x * x)
+ #define bar(y, z) (y + z)
- * ``bool AcrossEmptyLines`` Whether to align across empty lines.
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- .. code-block:: c++
+ int aaaa : 1;
+ int b : 12;
+ int ccc : 8;
- true:
- int a = 1;
- int somelongname = 2;
- double c = 3;
+ int aaaa = 12;
+ float b = 23;
+ std::string ccc;
+ ```
- int d = 3;
+ - `bool AcrossEmptyLines` Whether to align across empty lines.
- false:
- int a = 1;
- int somelongname = 2;
- double c = 3;
+ ```c++
+ true:
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- int d = 3;
+ int d = 3;
- * ``bool AcrossComments`` Whether to align across comments.
+ false:
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- .. code-block:: c++
+ int d = 3;
+ ```
- true:
- int d = 3;
- /* A comment. */
- double e = 4;
+ - `bool AcrossComments` Whether to align across comments.
- false:
- int d = 3;
- /* A comment. */
- double e = 4;
+ ```c++
+ true:
+ int d = 3;
+ /* A comment. */
+ double e = 4;
- * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments
- like ``+=`` are aligned along with ``=``.
+ false:
+ int d = 3;
+ /* A comment. */
+ double e = 4;
+ ```
- .. code-block:: c++
+ - `bool AlignCompound` Only for `AlignConsecutiveAssignments`. Whether compound assignments
+ like `+=` are aligned along with `=`.
- true:
- a &= 2;
- bbb = 2;
+ ```c++
+ true:
+ a &= 2;
+ bbb = 2;
- false:
- a &= 2;
- bbb = 2;
+ false:
+ a &= 2;
+ bbb = 2;
+ ```
- * ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations
+ - `bool AlignFunctionDeclarations` Only for `AlignConsecutiveDeclarations`. Whether function declarations
are aligned.
- .. code-block:: c++
-
- true:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
+ ```c++
+ true:
+ unsigned int f1(void);
+ void f2(void);
+ size_t f3(void);
- false:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
+ false:
+ unsigned int f1(void);
+ void f2(void);
+ size_t f3(void);
+ ```
- * ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are
+ - `bool AlignFunctionPointers` Only for `AlignConsecutiveDeclarations`. Whether function pointers are
aligned.
- .. code-block:: c++
-
- true:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- false:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- * ``bool EnumAssignments`` Only for ``AlignConsecutiveAssignments``.
- Whether enum assignments are aligned. If ``Enabled`` is ``false``,
- setting this to ``true`` forces alignment for enum assignments only.
- If ``Enabled`` is ``true``, enum assignments are always aligned.
+ ```c++
+ true:
+ unsigned i;
+ int &r;
+ int *p;
+ int (*f)();
- * ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment
+ false:
+ unsigned i;
+ int &r;
+ int *p;
+ int (*f)();
+ ```
+
+ - `bool EnumAssignments` Only for `AlignConsecutiveAssignments`.
+ Whether enum assignments are aligned. If `Enabled` is `false`,
+ setting this to `true` forces alignment for enum assignments only.
+ If `Enabled` is `true`, enum assignments are always aligned.
+
+ - `bool PadOperators` Only for `AlignConsecutiveAssignments`. Whether short assignment
operators are left-padded to the same length as long ones in order to
put all assignment operators to the right of the left hand side.
- .. code-block:: c++
-
- true:
- a >>= 2;
- bbb = 2;
-
- a = 2;
- bbb >>= 2;
+ ```c++
+ true:
+ a >>= 2;
+ bbb = 2;
- false:
- a >>= 2;
- bbb = 2;
+ a = 2;
+ bbb >>= 2;
- a = 2;
- bbb >>= 2;
+ false:
+ a >>= 2;
+ bbb = 2;
+ a = 2;
+ bbb >>= 2;
+ ```
-.. _AlignConsecutiveShortCaseStatements:
-**AlignConsecutiveShortCaseStatements** (``ShortCaseStatementsAlignmentStyle``) :versionbadge:`clang-format 17` :ref:`¶ <AlignConsecutiveShortCaseStatements>`
- Style of aligning consecutive short case labels.
- Only applies if ``AllowShortCaseExpressionOnASingleLine`` or
- ``AllowShortCaseLabelsOnASingleLine`` is ``true``.
+(alignconsecutiveshortcasestatements)=
+**AlignConsecutiveShortCaseStatements** (`ShortCaseStatementsAlignmentStyle`) {versionbadge}`clang-format 17` {ref}`¶ <AlignConsecutiveShortCaseStatements>`
- .. code-block:: yaml
+: Style of aligning consecutive short case labels.
+ Only applies if `AllowShortCaseExpressionOnASingleLine` or
+ `AllowShortCaseLabelsOnASingleLine` is `true`.
- # Example of usage:
- AlignConsecutiveShortCaseStatements:
- Enabled: true
- AcrossEmptyLines: true
- AcrossComments: true
- AlignCaseColons: false
+ ```yaml
+ # Example of usage:
+ AlignConsecutiveShortCaseStatements:
+ Enabled: true
+ AcrossEmptyLines: true
+ AcrossComments: true
+ AlignCaseColons: false
+ ```
Nested configuration flags:
Alignment options.
- * ``bool Enabled`` Whether aligning is enabled.
+ - `bool Enabled` Whether aligning is enabled.
- .. code-block:: c++
-
- true:
- switch (level) {
- case log::info: return "info:";
- case log::warning: return "warning:";
- default: return "";
- }
-
- false:
- switch (level) {
- case log::info: return "info:";
- case log::warning: return "warning:";
- default: return "";
- }
-
- * ``bool AcrossEmptyLines`` Whether to align across empty lines.
-
- .. code-block:: c++
+ ```c++
+ true:
+ switch (level) {
+ case log::info: return "info:";
+ case log::warning: return "warning:";
+ default: return "";
+ }
- true:
- switch (level) {
- case log::info: return "info:";
- case log::warning: return "warning:";
+ false:
+ switch (level) {
+ case log::info: return "info:";
+ case log::warning: return "warning:";
+ default: return "";
+ }
+ ```
- default: return "";
- }
+ - `bool AcrossEmptyLines` Whether to align across empty lines.
- false:
- switch (level) {
- case log::info: return "info:";
- case log::warning: return "warning:";
+ ```c++
+ true:
+ switch (level) {
+ case log::info: return "info:";
+ case log::warning: return "warning:";
- default: return "";
- }
+ default: return "";
+ }
- * ``bool AcrossComments`` Whether to align across comments.
+ false:
+ switch (level) {
+ case log::info: return "info:";
+ case log::warning: return "warning:";
- .. code-block:: c++
+ default: return "";
+ }
+ ```
- true:
- switch (level) {
- case log::info: return "info:";
- case log::warning: return "warning:";
- /* A comment. */
- default: return "";
- }
+ - `bool AcrossComments` Whether to align across comments.
- false:
- switch (level) {
- case log::info: return "info:";
- case log::warning: return "warning:";
- /* A comment. */
- default: return "";
- }
+ ```c++
+ true:
+ switch (level) {
+ case log::info: return "info:";
+ case log::warning: return "warning:";
+ /* A comment. */
+ default: return "";
+ }
- * ``bool AlignCaseArrows`` Whether to align the case arrows when aligning short case expressions.
+ false:
+ switch (level) {
+ case log::info: return "info:";
+ case log::warning: return "warning:";
+ /* A comment. */
+ default: return "";
+ }
+ ```
- .. code-block:: java
+ - `bool AlignCaseArrows` Whether to align the case arrows when aligning short case expressions.
- true:
- i = switch (day) {
- case THURSDAY, SATURDAY -> 8;
- case WEDNESDAY -> 9;
- default -> 0;
- };
+ ```java
+ true:
+ i = switch (day) {
+ case THURSDAY, SATURDAY -> 8;
+ case WEDNESDAY -> 9;
+ default -> 0;
+ };
- false:
- i = switch (day) {
- case THURSDAY, SATURDAY -> 8;
- case WEDNESDAY -> 9;
- default -> 0;
- };
+ false:
+ i = switch (day) {
+ case THURSDAY, SATURDAY -> 8;
+ case WEDNESDAY -> 9;
+ default -> 0;
+ };
+ ```
- * ``bool AlignCaseColons`` Whether aligned case labels are aligned on the colon, or on the tokens
+ - `bool AlignCaseColons` Whether aligned case labels are aligned on the colon, or on the tokens
after the colon.
- .. code-block:: c++
+ ```c++
+ true:
+ switch (level) {
+ case log::info : return "info:";
+ case log::warning: return "warning:";
+ default : return "";
+ }
- true:
- switch (level) {
- case log::info : return "info:";
- case log::warning: return "warning:";
- default : return "";
- }
+ false:
+ switch (level) {
+ case log::info: return "info:";
+ case log::warning: return "warning:";
+ default: return "";
+ }
+ ```
- false:
- switch (level) {
- case log::info: return "info:";
- case log::warning: return "warning:";
- default: return "";
- }
+(alignconsecutivetablegenbreakingdagargcolons)=
-.. _AlignConsecutiveTableGenBreakingDAGArgColons:
+**AlignConsecutiveTableGenBreakingDAGArgColons** (`AlignConsecutiveStyle`) {versionbadge}`clang-format 19` {ref}`¶ <AlignConsecutiveTableGenBreakingDAGArgColons>`
-**AlignConsecutiveTableGenBreakingDAGArgColons** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 19` :ref:`¶ <AlignConsecutiveTableGenBreakingDAGArgColons>`
- Style of aligning consecutive TableGen DAGArg operator colons.
+: Style of aligning consecutive TableGen DAGArg operator colons.
If enabled, align the colon inside DAGArg which have line break inside.
This works only when TableGenBreakInsideDAGArg is BreakElements or
BreakAll and the DAGArg is not excepted by
TableGenBreakingDAGArgOperators's effect.
- .. code-block:: c++
-
- let dagarg = (ins
- a :$src1,
- aa :$src2,
- aaa:$src3
- )
+ ```c++
+ let dagarg = (ins
+ a :$src1,
+ aa :$src2,
+ aaa:$src3
+ )
+ ```
Nested configuration flags:
@@ -1058,160 +1047,161 @@ the configuration (without a prefix: ``Auto``).
They can also be read as a whole for compatibility. The choices are:
- * ``None``
- * ``Consecutive``
- * ``AcrossEmptyLines``
- * ``AcrossComments``
- * ``AcrossEmptyLinesAndComments``
+ - `None`
+ - `Consecutive`
+ - `AcrossEmptyLines`
+ - `AcrossComments`
+ - `AcrossEmptyLinesAndComments`
For example, to align across empty lines and not across comments, either
of these work.
- .. code-block:: c++
-
- AlignConsecutiveTableGenBreakingDAGArgColons: AcrossEmptyLines
+ ```c++
+ AlignConsecutiveTableGenBreakingDAGArgColons: AcrossEmptyLines
- AlignConsecutiveTableGenBreakingDAGArgColons:
- Enabled: true
- AcrossEmptyLines: true
- AcrossComments: false
+ AlignConsecutiveTableGenBreakingDAGArgColons:
+ Enabled: true
+ AcrossEmptyLines: true
+ AcrossComments: false
+ ```
- * ``bool Enabled`` Whether aligning is enabled.
+ - `bool Enabled` Whether aligning is enabled.
- .. code-block:: c++
-
- #define SHORT_NAME 42
- #define LONGER_NAME 0x007f
- #define EVEN_LONGER_NAME (2)
- #define foo(x) (x * x)
- #define bar(y, z) (y + z)
+ ```c++
+ #define SHORT_NAME 42
+ #define LONGER_NAME 0x007f
+ #define EVEN_LONGER_NAME (2)
+ #define foo(x) (x * x)
+ #define bar(y, z) (y + z)
- int a = 1;
- int somelongname = 2;
- double c = 3;
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- int aaaa : 1;
- int b : 12;
- int ccc : 8;
+ int aaaa : 1;
+ int b : 12;
+ int ccc : 8;
- int aaaa = 12;
- float b = 23;
- std::string ccc;
-
- * ``bool AcrossEmptyLines`` Whether to align across empty lines.
-
- .. code-block:: c++
-
- true:
- int a = 1;
- int somelongname = 2;
- double c = 3;
+ int aaaa = 12;
+ float b = 23;
+ std::string ccc;
+ ```
- int d = 3;
+ - `bool AcrossEmptyLines` Whether to align across empty lines.
- false:
- int a = 1;
- int somelongname = 2;
- double c = 3;
+ ```c++
+ true:
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- int d = 3;
+ int d = 3;
- * ``bool AcrossComments`` Whether to align across comments.
+ false:
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- .. code-block:: c++
+ int d = 3;
+ ```
- true:
- int d = 3;
- /* A comment. */
- double e = 4;
+ - `bool AcrossComments` Whether to align across comments.
- false:
- int d = 3;
- /* A comment. */
- double e = 4;
+ ```c++
+ true:
+ int d = 3;
+ /* A comment. */
+ double e = 4;
- * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments
- like ``+=`` are aligned along with ``=``.
+ false:
+ int d = 3;
+ /* A comment. */
+ double e = 4;
+ ```
- .. code-block:: c++
+ - `bool AlignCompound` Only for `AlignConsecutiveAssignments`. Whether compound assignments
+ like `+=` are aligned along with `=`.
- true:
- a &= 2;
- bbb = 2;
+ ```c++
+ true:
+ a &= 2;
+ bbb = 2;
- false:
- a &= 2;
- bbb = 2;
+ false:
+ a &= 2;
+ bbb = 2;
+ ```
- * ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations
+ - `bool AlignFunctionDeclarations` Only for `AlignConsecutiveDeclarations`. Whether function declarations
are aligned.
- .. code-block:: c++
-
- true:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
+ ```c++
+ true:
+ unsigned int f1(void);
+ void f2(void);
+ size_t f3(void);
- false:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
+ false:
+ unsigned int f1(void);
+ void f2(void);
+ size_t f3(void);
+ ```
- * ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are
+ - `bool AlignFunctionPointers` Only for `AlignConsecutiveDeclarations`. Whether function pointers are
aligned.
- .. code-block:: c++
-
- true:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- false:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- * ``bool EnumAssignments`` Only for ``AlignConsecutiveAssignments``.
- Whether enum assignments are aligned. If ``Enabled`` is ``false``,
- setting this to ``true`` forces alignment for enum assignments only.
- If ``Enabled`` is ``true``, enum assignments are always aligned.
+ ```c++
+ true:
+ unsigned i;
+ int &r;
+ int *p;
+ int (*f)();
- * ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment
+ false:
+ unsigned i;
+ int &r;
+ int *p;
+ int (*f)();
+ ```
+
+ - `bool EnumAssignments` Only for `AlignConsecutiveAssignments`.
+ Whether enum assignments are aligned. If `Enabled` is `false`,
+ setting this to `true` forces alignment for enum assignments only.
+ If `Enabled` is `true`, enum assignments are always aligned.
+
+ - `bool PadOperators` Only for `AlignConsecutiveAssignments`. Whether short assignment
operators are left-padded to the same length as long ones in order to
put all assignment operators to the right of the left hand side.
- .. code-block:: c++
+ ```c++
+ true:
+ a >>= 2;
+ bbb = 2;
- true:
- a >>= 2;
- bbb = 2;
+ a = 2;
+ bbb >>= 2;
- a = 2;
- bbb >>= 2;
+ false:
+ a >>= 2;
+ bbb = 2;
- false:
- a >>= 2;
- bbb = 2;
+ a = 2;
+ bbb >>= 2;
+ ```
- a = 2;
- bbb >>= 2;
+(alignconsecutivetablegencondoperatorcolons)=
-.. _AlignConsecutiveTableGenCondOperatorColons:
+**AlignConsecutiveTableGenCondOperatorColons** (`AlignConsecutiveStyle`) {versionbadge}`clang-format 19` {ref}`¶ <AlignConsecutiveTableGenCondOperatorColons>`
-**AlignConsecutiveTableGenCondOperatorColons** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 19` :ref:`¶ <AlignConsecutiveTableGenCondOperatorColons>`
- Style of aligning consecutive TableGen cond operator colons.
+: Style of aligning consecutive TableGen cond operator colons.
Align the colons of cases inside !cond operators.
- .. code-block:: c++
-
- !cond(!eq(size, 1) : 1,
- !eq(size, 16): 1,
- true : 0)
+ ```c++
+ !cond(!eq(size, 1) : 1,
+ !eq(size, 16): 1,
+ true : 0)
+ ```
Nested configuration flags:
@@ -1219,160 +1209,161 @@ the configuration (without a prefix: ``Auto``).
They can also be read as a whole for compatibility. The choices are:
- * ``None``
- * ``Consecutive``
- * ``AcrossEmptyLines``
- * ``AcrossComments``
- * ``AcrossEmptyLinesAndComments``
+ - `None`
+ - `Consecutive`
+ - `AcrossEmptyLines`
+ - `AcrossComments`
+ - `AcrossEmptyLinesAndComments`
For example, to align across empty lines and not across comments, either
of these work.
- .. code-block:: c++
-
- AlignConsecutiveTableGenCondOperatorColons: AcrossEmptyLines
-
- AlignConsecutiveTableGenCondOperatorColons:
- Enabled: true
- AcrossEmptyLines: true
- AcrossComments: false
-
- * ``bool Enabled`` Whether aligning is enabled.
+ ```c++
+ AlignConsecutiveTableGenCondOperatorColons: AcrossEmptyLines
- .. code-block:: c++
+ AlignConsecutiveTableGenCondOperatorColons:
+ Enabled: true
+ AcrossEmptyLines: true
+ AcrossComments: false
+ ```
- #define SHORT_NAME 42
- #define LONGER_NAME 0x007f
- #define EVEN_LONGER_NAME (2)
- #define foo(x) (x * x)
- #define bar(y, z) (y + z)
+ - `bool Enabled` Whether aligning is enabled.
- int a = 1;
- int somelongname = 2;
- double c = 3;
-
- int aaaa : 1;
- int b : 12;
- int ccc : 8;
-
- int aaaa = 12;
- float b = 23;
- std::string ccc;
+ ```c++
+ #define SHORT_NAME 42
+ #define LONGER_NAME 0x007f
+ #define EVEN_LONGER_NAME (2)
+ #define foo(x) (x * x)
+ #define bar(y, z) (y + z)
- * ``bool AcrossEmptyLines`` Whether to align across empty lines.
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- .. code-block:: c++
+ int aaaa : 1;
+ int b : 12;
+ int ccc : 8;
- true:
- int a = 1;
- int somelongname = 2;
- double c = 3;
+ int aaaa = 12;
+ float b = 23;
+ std::string ccc;
+ ```
- int d = 3;
+ - `bool AcrossEmptyLines` Whether to align across empty lines.
- false:
- int a = 1;
- int somelongname = 2;
- double c = 3;
+ ```c++
+ true:
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- int d = 3;
+ int d = 3;
- * ``bool AcrossComments`` Whether to align across comments.
+ false:
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- .. code-block:: c++
+ int d = 3;
+ ```
- true:
- int d = 3;
- /* A comment. */
- double e = 4;
+ - `bool AcrossComments` Whether to align across comments.
- false:
- int d = 3;
- /* A comment. */
- double e = 4;
+ ```c++
+ true:
+ int d = 3;
+ /* A comment. */
+ double e = 4;
- * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments
- like ``+=`` are aligned along with ``=``.
+ false:
+ int d = 3;
+ /* A comment. */
+ double e = 4;
+ ```
- .. code-block:: c++
+ - `bool AlignCompound` Only for `AlignConsecutiveAssignments`. Whether compound assignments
+ like `+=` are aligned along with `=`.
- true:
- a &= 2;
- bbb = 2;
+ ```c++
+ true:
+ a &= 2;
+ bbb = 2;
- false:
- a &= 2;
- bbb = 2;
+ false:
+ a &= 2;
+ bbb = 2;
+ ```
- * ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations
+ - `bool AlignFunctionDeclarations` Only for `AlignConsecutiveDeclarations`. Whether function declarations
are aligned.
- .. code-block:: c++
-
- true:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
+ ```c++
+ true:
+ unsigned int f1(void);
+ void f2(void);
+ size_t f3(void);
- false:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
+ false:
+ unsigned int f1(void);
+ void f2(void);
+ size_t f3(void);
+ ```
- * ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are
+ - `bool AlignFunctionPointers` Only for `AlignConsecutiveDeclarations`. Whether function pointers are
aligned.
- .. code-block:: c++
-
- true:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- false:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- * ``bool EnumAssignments`` Only for ``AlignConsecutiveAssignments``.
- Whether enum assignments are aligned. If ``Enabled`` is ``false``,
- setting this to ``true`` forces alignment for enum assignments only.
- If ``Enabled`` is ``true``, enum assignments are always aligned.
+ ```c++
+ true:
+ unsigned i;
+ int &r;
+ int *p;
+ int (*f)();
- * ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment
+ false:
+ unsigned i;
+ int &r;
+ int *p;
+ int (*f)();
+ ```
+
+ - `bool EnumAssignments` Only for `AlignConsecutiveAssignments`.
+ Whether enum assignments are aligned. If `Enabled` is `false`,
+ setting this to `true` forces alignment for enum assignments only.
+ If `Enabled` is `true`, enum assignments are always aligned.
+
+ - `bool PadOperators` Only for `AlignConsecutiveAssignments`. Whether short assignment
operators are left-padded to the same length as long ones in order to
put all assignment operators to the right of the left hand side.
- .. code-block:: c++
+ ```c++
+ true:
+ a >>= 2;
+ bbb = 2;
- true:
- a >>= 2;
- bbb = 2;
+ a = 2;
+ bbb >>= 2;
- a = 2;
- bbb >>= 2;
+ false:
+ a >>= 2;
+ bbb = 2;
- false:
- a >>= 2;
- bbb = 2;
+ a = 2;
+ bbb >>= 2;
+ ```
- a = 2;
- bbb >>= 2;
+(alignconsecutivetablegendefinitioncolons)=
-.. _AlignConsecutiveTableGenDefinitionColons:
+**AlignConsecutiveTableGenDefinitionColons** (`AlignConsecutiveStyle`) {versionbadge}`clang-format 19` {ref}`¶ <AlignConsecutiveTableGenDefinitionColons>`
-**AlignConsecutiveTableGenDefinitionColons** (``AlignConsecutiveStyle``) :versionbadge:`clang-format 19` :ref:`¶ <AlignConsecutiveTableGenDefinitionColons>`
- Style of aligning consecutive TableGen definition colons.
+: Style of aligning consecutive TableGen definition colons.
This aligns the inheritance colons of consecutive definitions.
- .. code-block:: c++
-
- def Def : Parent {}
- def DefDef : Parent {}
- def DefDefDef : Parent {}
+ ```c++
+ def Def : Parent {}
+ def DefDef : Parent {}
+ def DefDefDef : Parent {}
+ ```
Nested configuration flags:
@@ -1380,558 +1371,570 @@ the configuration (without a prefix: ``Auto``).
They can also be read as a whole for compatibility. The choices are:
- * ``None``
- * ``Consecutive``
- * ``AcrossEmptyLines``
- * ``AcrossComments``
- * ``AcrossEmptyLinesAndComments``
+ - `None`
+ - `Consecutive`
+ - `AcrossEmptyLines`
+ - `AcrossComments`
+ - `AcrossEmptyLinesAndComments`
For example, to align across empty lines and not across comments, either
of these work.
- .. code-block:: c++
-
- AlignConsecutiveTableGenDefinitionColons: AcrossEmptyLines
+ ```c++
+ AlignConsecutiveTableGenDefinitionColons: AcrossEmptyLines
- AlignConsecutiveTableGenDefinitionColons:
- Enabled: true
- AcrossEmptyLines: true
- AcrossComments: false
+ AlignConsecutiveTableGenDefinitionColons:
+ Enabled: true
+ AcrossEmptyLines: true
+ AcrossComments: false
+ ```
- * ``bool Enabled`` Whether aligning is enabled.
+ - `bool Enabled` Whether aligning is enabled.
- .. code-block:: c++
-
- #define SHORT_NAME 42
- #define LONGER_NAME 0x007f
- #define EVEN_LONGER_NAME (2)
- #define foo(x) (x * x)
- #define bar(y, z) (y + z)
-
- int a = 1;
- int somelongname = 2;
- double c = 3;
-
- int aaaa : 1;
- int b : 12;
- int ccc : 8;
-
- int aaaa = 12;
- float b = 23;
- std::string ccc;
+ ```c++
+ #define SHORT_NAME 42
+ #define LONGER_NAME 0x007f
+ #define EVEN_LONGER_NAME (2)
+ #define foo(x) (x * x)
+ #define bar(y, z) (y + z)
- * ``bool AcrossEmptyLines`` Whether to align across empty lines.
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- .. code-block:: c++
+ int aaaa : 1;
+ int b : 12;
+ int ccc : 8;
- true:
- int a = 1;
- int somelongname = 2;
- double c = 3;
+ int aaaa = 12;
+ float b = 23;
+ std::string ccc;
+ ```
- int d = 3;
+ - `bool AcrossEmptyLines` Whether to align across empty lines.
- false:
- int a = 1;
- int somelongname = 2;
- double c = 3;
+ ```c++
+ true:
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- int d = 3;
+ int d = 3;
- * ``bool AcrossComments`` Whether to align across comments.
+ false:
+ int a = 1;
+ int somelongname = 2;
+ double c = 3;
- .. code-block:: c++
+ int d = 3;
+ ```
- true:
- int d = 3;
- /* A comment. */
- double e = 4;
+ - `bool AcrossComments` Whether to align across comments.
- false:
- int d = 3;
- /* A comment. */
- double e = 4;
+ ```c++
+ true:
+ int d = 3;
+ /* A comment. */
+ double e = 4;
- * ``bool AlignCompound`` Only for ``AlignConsecutiveAssignments``. Whether compound assignments
- like ``+=`` are aligned along with ``=``.
+ false:
+ int d = 3;
+ /* A comment. */
+ double e = 4;
+ ```
- .. code-block:: c++
+ - `bool AlignCompound` Only for `AlignConsecutiveAssignments`. Whether compound assignments
+ like `+=` are aligned along with `=`.
- true:
- a &= 2;
- bbb = 2;
+ ```c++
+ true:
+ a &= 2;
+ bbb = 2;
- false:
- a &= 2;
- bbb = 2;
+ false:
+ a &= 2;
+ bbb = 2;
+ ```
- * ``bool AlignFunctionDeclarations`` Only for ``AlignConsecutiveDeclarations``. Whether function declarations
+ - `bool AlignFunctionDeclarations` Only for `AlignConsecutiveDeclarations`. Whether function declarations
are aligned.
- .. code-block:: c++
-
- true:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
+ ```c++
+ true:
+ unsigned int f1(void);
+ void f2(void);
+ size_t f3(void);
- false:
- unsigned int f1(void);
- void f2(void);
- size_t f3(void);
+ false:
+ unsigned int f1(void);
+ void f2(void);
+ size_t f3(void);
+ ```
- * ``bool AlignFunctionPointers`` Only for ``AlignConsecutiveDeclarations``. Whether function pointers are
+ - `bool AlignFunctionPointers` Only for `AlignConsecutiveDeclarations`. Whether function pointers are
aligned.
- .. code-block:: c++
-
- true:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- false:
- unsigned i;
- int &r;
- int *p;
- int (*f)();
-
- * ``bool EnumAssignments`` Only for ``AlignConsecutiveAssignments``.
- Whether enum assignments are aligned. If ``Enabled`` is ``false``,
- setting this to ``true`` forces alignment for enum assignments only.
- If ``Enabled`` is ``true``, enum assignments are always aligned.
+ ```c++
+ true:
+ unsigned i;
+ int &r;
+ int *p;
+ int (*f)();
- * ``bool PadOperators`` Only for ``AlignConsecutiveAssignments``. Whether short assignment
+ false:
+ unsigned i;
+ int &r;
+ int *p;
+ int (*f)();
+ ```
+
+ - `bool EnumAssignments` Only for `AlignConsecutiveAssignments`.
+ Whether enum assignments are aligned. If `Enabled` is `false`,
+ setting this to `true` forces alignment for enum assignments only.
+ If `Enabled` is `true`, enum assignments are always aligned.
+
+ - `bool PadOperators` Only for `AlignConsecutiveAssignments`. Whether short assignment
operators are left-padded to the same length as long ones in order to
put all assignment operators to the right of the left hand side.
- .. code-block:: c++
+ ```c++
+ true:
+ a >>= 2;
+ bbb = 2;
- true:
- a >>= 2;
- bbb = 2;
+ a = 2;
+ bbb >>= 2;
- a = 2;
- bbb >>= 2;
+ false:
+ a >>= 2;
+ bbb = 2;
- false:
- a >>= 2;
- bbb = 2;
+ a = 2;
+ bbb >>= 2;
+ ```
- a = 2;
- bbb >>= 2;
+(alignescapednewlines)=
-.. _AlignEscapedNewlines:
+**AlignEscapedNewlines** (`EscapedNewlineAlignmentStyle`) {versionbadge}`clang-format 5` {ref}`¶ <AlignEscapedNewlines>`
-**AlignEscapedNewlines** (``EscapedNewlineAlignmentStyle``) :versionbadge:`clang-format 5` :ref:`¶ <AlignEscapedNewlines>`
- Options for aligning backslashes in escaped newlines.
+: Options for aligning backslashes in escaped newlines.
Possible values:
- * ``ENAS_DontAlign`` (in configuration: ``DontAlign``)
+ - `ENAS_DontAlign` (in configuration: `DontAlign`)
Don't align escaped newlines.
- .. code-block:: c++
+ ```c++
+ #define A \
+ int aaaa; \
+ int b; \
+ int dddddddddd;
+ ```
- #define A \
- int aaaa; \
- int b; \
- int dddddddddd;
-
- * ``ENAS_Left`` (in configuration: ``Left``)
+ - `ENAS_Left` (in configuration: `Left`)
Align escaped newlines as far left as possible.
- .. code-block:: c++
-
- #define A \
- int aaaa; \
- int b; \
- int dddddddddd;
+ ```c++
+ #define A \
+ int aaaa; \
+ int b; \
+ int dddddddddd;
+ ```
- * ``ENAS_LeftWithLastLine`` (in configuration: ``LeftWithLastLine``)
+ - `ENAS_LeftWithLastLine` (in configuration: `LeftWithLastLine`)
Align escaped newlines as far left as possible, using the last line of
the preprocessor directive as the reference if it's the longest.
- .. code-block:: c++
+ ```c++
+ #define A \
+ int aaaa; \
+ int b; \
+ int dddddddddd;
+ ```
- #define A \
- int aaaa; \
- int b; \
- int dddddddddd;
-
- * ``ENAS_Right`` (in configuration: ``Right``)
+ - `ENAS_Right` (in configuration: `Right`)
Align escaped newlines in the right-most column.
- .. code-block:: c++
+ ```c++
+ #define A \
+ int aaaa; \
+ int b; \
+ int dddddddddd;
+ ```
- #define A \
- int aaaa; \
- int b; \
- int dddddddddd;
+(alignoperands)=
-.. _AlignOperands:
+**AlignOperands** (`OperandAlignmentStyle`) {versionbadge}`clang-format 3.5` {ref}`¶ <AlignOperands>`
-**AlignOperands** (``OperandAlignmentStyle``) :versionbadge:`clang-format 3.5` :ref:`¶ <AlignOperands>`
- If ``true``, horizontally align operands of binary and ternary
+: If `true`, horizontally align operands of binary and ternary
expressions.
Possible values:
- * ``OAS_DontAlign`` (in configuration: ``DontAlign``)
+ - `OAS_DontAlign` (in configuration: `DontAlign`)
Do not align operands of binary and ternary expressions.
- The wrapped lines are indented ``ContinuationIndentWidth`` spaces from
+ The wrapped lines are indented `ContinuationIndentWidth` spaces from
the start of the line.
- * ``OAS_Align`` (in configuration: ``Align``)
+ - `OAS_Align` (in configuration: `Align`)
Horizontally align operands of binary and ternary expressions.
Specifically, this aligns operands of a single expression that needs
to be split over multiple lines, e.g.:
- .. code-block:: c++
-
- int aaa = bbbbbbbbbbbbbbb +
- ccccccccccccccc;
+ ```c++
+ int aaa = bbbbbbbbbbbbbbb +
+ ccccccccccccccc;
+ ```
- When ``BreakBeforeBinaryOperators`` is set, the wrapped operator is
+ When `BreakBeforeBinaryOperators` is set, the wrapped operator is
aligned with the operand on the first line.
- .. code-block:: c++
-
- int aaa = bbbbbbbbbbbbbbb
- + ccccccccccccccc;
+ ```c++
+ int aaa = bbbbbbbbbbbbbbb
+ + ccccccccccccccc;
+ ```
- * ``OAS_AlignAfterOperator`` (in configuration: ``AlignAfterOperator``)
+ - `OAS_AlignAfterOperator` (in configuration: `AlignAfterOperator`)
Horizontally align operands of binary and ternary expressions.
- This is similar to ``OAS_Align``, except when
- ``BreakBeforeBinaryOperators`` is set, the operator is un-indented so
+ This is similar to `OAS_Align`, except when
+ `BreakBeforeBinaryOperators` is set, the operator is un-indented so
that the wrapped operand is aligned with the operand on the first line.
- .. code-block:: c++
+ ```c++
+ int aaa = bbbbbbbbbbbbbbb
+ + ccccccccccccccc;
+ ```
- int aaa = bbbbbbbbbbbbbbb
- + ccccccccccccccc;
+(aligntrailingcomments)=
-.. _AlignTrailingComments:
+**AlignTrailingComments** (`TrailingCommentsAlignmentStyle`) {versionbadge}`clang-format 3.7` {ref}`¶ <AlignTrailingComments>`
-**AlignTrailingComments** (``TrailingCommentsAlignmentStyle``) :versionbadge:`clang-format 3.7` :ref:`¶ <AlignTrailingComments>`
- Control of trailing comments.
+: Control of trailing comments.
The alignment stops at closing braces after a line break, and only
- followed by other closing braces, a (``do-``) ``while``, a lambda call, or
+ followed by other closing braces, a (`do-`) `while`, a lambda call, or
a semicolon.
+ :::{note}
+ As of clang-format 16 this option is not a bool but can be set
+ to the options. Conventional bool options still can be parsed as before.
+ :::
- .. note::
-
- As of clang-format 16 this option is not a bool but can be set
- to the options. Conventional bool options still can be parsed as before.
-
-
- .. code-block:: yaml
-
- # Example of usage:
- AlignTrailingComments:
- Kind: Always
- OverEmptyLines: 2
+ ```yaml
+ # Example of usage:
+ AlignTrailingComments:
+ Kind: Always
+ OverEmptyLines: 2
+ ```
Nested configuration flags:
Alignment options
- * ``TrailingCommentsAlignmentKinds Kind``
+ - `TrailingCommentsAlignmentKinds Kind`
Specifies the way to align trailing comments.
Possible values:
- * ``TCAS_Leave`` (in configuration: ``Leave``)
+ - `TCAS_Leave` (in configuration: `Leave`)
Leave trailing comments as they are.
- .. code-block:: c++
-
- int a; // comment
- int ab; // comment
+ ```c++
+ int a; // comment
+ int ab; // comment
- int abc; // comment
- int abcd; // comment
+ int abc; // comment
+ int abcd; // comment
+ ```
- * ``TCAS_Always`` (in configuration: ``Always``)
+ - `TCAS_Always` (in configuration: `Always`)
Align trailing comments.
- .. code-block:: c++
+ ```c++
+ int a; // comment
+ int ab; // comment
- int a; // comment
- int ab; // comment
+ int abc; // comment
+ int abcd; // comment
+ ```
- int abc; // comment
- int abcd; // comment
-
- * ``TCAS_Never`` (in configuration: ``Never``)
+ - `TCAS_Never` (in configuration: `Never`)
Don't align trailing comments but other formatter applies.
- .. code-block:: c++
-
- int a; // comment
- int ab; // comment
+ ```c++
+ int a; // comment
+ int ab; // comment
- int abc; // comment
- int abcd; // comment
+ int abc; // comment
+ int abcd; // comment
+ ```
- * ``unsigned OverEmptyLines`` How many empty lines to apply alignment.
- When both ``MaxEmptyLinesToKeep`` and ``OverEmptyLines`` are set to 2,
+ - `unsigned OverEmptyLines` How many empty lines to apply alignment.
+ When both `MaxEmptyLinesToKeep` and `OverEmptyLines` are set to 2,
it formats like below.
- .. code-block:: c++
+ ```c++
+ int a; // all these
- int a; // all these
+ int ab; // comments are
- int ab; // comments are
+ int abcdef; // aligned
+ ```
- int abcdef; // aligned
-
- When ``MaxEmptyLinesToKeep`` is set to 2 and ``OverEmptyLines`` is set
+ When `MaxEmptyLinesToKeep` is set to 2 and `OverEmptyLines` is set
to 1, it formats like below.
- .. code-block:: c++
-
- int a; // these are
+ ```c++
+ int a; // these are
- int ab; // aligned
+ int ab; // aligned
- int abcdef; // but this isn't
+ int abcdef; // but this isn't
+ ```
- * ``bool AlignPPAndNotPP`` If comments following preprocessor directive should be aligned with
+ - `bool AlignPPAndNotPP` If comments following preprocessor directive should be aligned with
comments that don't.
- .. code-block:: c++
+ ```c++
+ true: false:
+ #define A // Comment vs. #define A // Comment
+ #define AB // Aligned #define AB // Aligned
+ int i; // Aligned int i; // Not aligned
+ ```
- true: false:
- #define A // Comment vs. #define A // Comment
- #define AB // Aligned #define AB // Aligned
- int i; // Aligned int i; // Not aligned
+(allowallargumentsonnextline)=
-.. _AllowAllArgumentsOnNextLine:
+**AllowAllArgumentsOnNextLine** (`Boolean`) {versionbadge}`clang-format 9` {ref}`¶ <AllowAllArgumentsOnNextLine>`
-**AllowAllArgumentsOnNextLine** (``Boolean``) :versionbadge:`clang-format 9` :ref:`¶ <AllowAllArgumentsOnNextLine>`
- If a function call or braced initializer list doesn't fit on a line, allow
- putting all arguments onto the next line, even if ``BinPackArguments`` is
- ``false``.
+: If a function call or braced initializer list doesn't fit on a line, allow
+ putting all arguments onto the next line, even if `BinPackArguments` is
+ `false`.
- .. code-block:: c++
+ ```c++
+ true:
+ callFunction(
+ a, b, c, d);
- true:
- callFunction(
- a, b, c, d);
+ false:
+ callFunction(a,
+ b,
+ c,
+ d);
+ ```
- false:
- callFunction(a,
- b,
- c,
- d);
+(allowallconstructorinitializersonnextline)=
+
+**AllowAllConstructorInitializersOnNextLine** (`Boolean`) {versionbadge}`clang-format 9` {ref}`¶ <AllowAllConstructorInitializersOnNextLine>`
-.. _AllowAllConstructorInitializersOnNextLine:
+: This option is **deprecated**. See `NextLine` of
+ `PackConstructorInitializers`.
-**AllowAllConstructorInitializersOnNextLine** (``Boolean``) :versionbadge:`clang-format 9` :ref:`¶ <AllowAllConstructorInitializersOnNextLine>`
- This option is **deprecated**. See ``NextLine`` of
- ``PackConstructorInitializers``.
+(allowallparametersofdeclarationonnextline)=
-.. _AllowAllParametersOfDeclarationOnNextLine:
+**AllowAllParametersOfDeclarationOnNextLine** (`Boolean`) {versionbadge}`clang-format 3.3` {ref}`¶ <AllowAllParametersOfDeclarationOnNextLine>`
-**AllowAllParametersOfDeclarationOnNextLine** (``Boolean``) :versionbadge:`clang-format 3.3` :ref:`¶ <AllowAllParametersOfDeclarationOnNextLine>`
- If the function declaration doesn't fit on a line,
+: If the function declaration doesn't fit on a line,
allow putting all parameters of a function declaration onto
- the next line even if ``BinPackParameters`` is ``OnePerLine``.
+ the next line even if `BinPackParameters` is `OnePerLine`.
- .. code-block:: c++
+ ```c++
+ true:
+ void myFunction(
+ int a, int b, int c, int d, int e);
- true:
- void myFunction(
- int a, int b, int c, int d, int e);
+ false:
+ void myFunction(int a,
+ int b,
+ int c,
+ int d,
+ int e);
+ ```
- false:
- void myFunction(int a,
- int b,
- int c,
- int d,
- int e);
+(allowbreakbeforenoexceptspecifier)=
-.. _AllowBreakBeforeNoexceptSpecifier:
+**AllowBreakBeforeNoexceptSpecifier** (`BreakBeforeNoexceptSpecifierStyle`) {versionbadge}`clang-format 18` {ref}`¶ <AllowBreakBeforeNoexceptSpecifier>`
-**AllowBreakBeforeNoexceptSpecifier** (``BreakBeforeNoexceptSpecifierStyle``) :versionbadge:`clang-format 18` :ref:`¶ <AllowBreakBeforeNoexceptSpecifier>`
- Controls if there could be a line break before a ``noexcept`` specifier.
+: Controls if there could be a line break before a `noexcept` specifier.
Possible values:
- * ``BBNSS_Never`` (in configuration: ``Never``)
+ - `BBNSS_Never` (in configuration: `Never`)
No line break allowed.
- .. code-block:: c++
+ ```c++
+ void foo(int arg1,
+ double arg2) noexcept;
- void foo(int arg1,
- double arg2) noexcept;
+ void bar(int arg1, double arg2) noexcept(
+ noexcept(baz(arg1)) &&
+ noexcept(baz(arg2)));
+ ```
- void bar(int arg1, double arg2) noexcept(
- noexcept(baz(arg1)) &&
- noexcept(baz(arg2)));
-
- * ``BBNSS_OnlyWithParen`` (in configuration: ``OnlyWithParen``)
- For a simple ``noexcept`` there is no line break allowed, but when we
+ - `BBNSS_OnlyWithParen` (in configuration: `OnlyWithParen`)
+ For a simple `noexcept` there is no line break allowed, but when we
have a condition it is.
- .. code-block:: c++
-
- void foo(int arg1,
- double arg2) noexcept;
+ ```c++
+ void foo(int arg1,
+ double arg2) noexcept;
- void bar(int arg1, double arg2)
- noexcept(noexcept(baz(arg1)) &&
- noexcept(baz(arg2)));
+ void bar(int arg1, double arg2)
+ noexcept(noexcept(baz(arg1)) &&
+ noexcept(baz(arg2)));
+ ```
- * ``BBNSS_Always`` (in configuration: ``Always``)
+ - `BBNSS_Always` (in configuration: `Always`)
Line breaks are allowed. But note that because of the associated
- penalties ``clang-format`` often prefers not to break before the
- ``noexcept``.
+ penalties `clang-format` often prefers not to break before the
+ `noexcept`.
- .. code-block:: c++
+ ```c++
+ void foo(int arg1,
+ double arg2) noexcept;
- void foo(int arg1,
- double arg2) noexcept;
+ void bar(int arg1, double arg2)
+ noexcept(noexcept(baz(arg1)) &&
+ noexcept(baz(arg2)));
+ ```
- void bar(int arg1, double arg2)
- noexcept(noexcept(baz(arg1)) &&
- noexcept(baz(arg2)));
+(allowbreakbeforeqtproperty)=
-.. _AllowBreakBeforeQtProperty:
+**AllowBreakBeforeQtProperty** (`Boolean`) {versionbadge}`clang-format 22` {ref}`¶ <AllowBreakBeforeQtProperty>`
-**AllowBreakBeforeQtProperty** (``Boolean``) :versionbadge:`clang-format 22` :ref:`¶ <AllowBreakBeforeQtProperty>`
- Allow breaking before ``Q_Property`` keywords ``READ``, ``WRITE``, etc. as
- if they were preceded by a comma (``,``). This allows them to be formatted
- according to ``BinPackParameters``.
+: Allow breaking before `Q_Property` keywords `READ`, `WRITE`, etc. as
+ if they were preceded by a comma (`,`). This allows them to be formatted
+ according to `BinPackParameters`.
-.. _AllowShortBlocksOnASingleLine:
+(allowshortblocksonasingleline)=
-**AllowShortBlocksOnASingleLine** (``ShortBlockStyle``) :versionbadge:`clang-format 3.5` :ref:`¶ <AllowShortBlocksOnASingleLine>`
- Dependent on the value, ``while (true) { continue; }`` can be put on a
+**AllowShortBlocksOnASingleLine** (`ShortBlockStyle`) {versionbadge}`clang-format 3.5` {ref}`¶ <AllowShortBlocksOnASingleLine>`
+
+: Dependent on the value, `while (true) { continue; }` can be put on a
single line.
Possible values:
- * ``SBS_Never`` (in configuration: ``Never``)
+ - `SBS_Never` (in configuration: `Never`)
Never merge blocks into a single line.
- .. code-block:: c++
-
- while (true) {
- }
- while (true) {
- continue;
- }
+ ```c++
+ while (true) {
+ }
+ while (true) {
+ continue;
+ }
+ ```
- * ``SBS_Empty`` (in configuration: ``Empty``)
+ - `SBS_Empty` (in configuration: `Empty`)
Only merge empty blocks.
- .. code-block:: c++
-
- while (true) {}
- while (true) {
- continue;
- }
+ ```c++
+ while (true) {}
+ while (true) {
+ continue;
+ }
+ ```
- * ``SBS_Always`` (in configuration: ``Always``)
+ - `SBS_Always` (in configuration: `Always`)
Always merge short blocks into a single line.
- .. code-block:: c++
+ ```c++
+ while (true) {}
+ while (true) { continue; }
+ ```
- while (true) {}
- while (true) { continue; }
+(allowshortcaseexpressiononasingleline)=
-.. _AllowShortCaseExpressionOnASingleLine:
+**AllowShortCaseExpressionOnASingleLine** (`Boolean`) {versionbadge}`clang-format 19` {ref}`¶ <AllowShortCaseExpressionOnASingleLine>`
-**AllowShortCaseExpressionOnASingleLine** (``Boolean``) :versionbadge:`clang-format 19` :ref:`¶ <AllowShortCaseExpressionOnASingleLine>`
- Whether to merge a short switch labeled rule into a single line.
+: Whether to merge a short switch labeled rule into a single line.
- .. code-block:: java
+ ```java
+ true: false:
+ switch (a) { vs. switch (a) {
+ case 1 -> 1; case 1 ->
+ default -> 0; 1;
+ }; default ->
+ 0;
+ };
+ ```
- true: false:
- switch (a) { vs. switch (a) {
- case 1 -> 1; case 1 ->
- default -> 0; 1;
- }; default ->
- 0;
- };
-
-.. _AllowShortCaseLabelsOnASingleLine:
-
-**AllowShortCaseLabelsOnASingleLine** (``Boolean``) :versionbadge:`clang-format 3.6` :ref:`¶ <AllowShortCaseLabelsOnASingleLine>`
- If ``true``, short case labels will be contracted to a single line.
-
- .. code-block:: c++
-
- true: false:
- switch (a) { vs. switch (a) {
- case 1: x = 1; break; case 1:
- case 2: return; x = 1;
- } break;
- case 2:
- return;
- }
+(allowshortcaselabelsonasingleline)=
-.. _AllowShortCompoundRequirementOnASingleLine:
+**AllowShortCaseLabelsOnASingleLine** (`Boolean`) {versionbadge}`clang-format 3.6` {ref}`¶ <AllowShortCaseLabelsOnASingleLine>`
-**AllowShortCompoundRequirementOnASingleLine** (``Boolean``) :versionbadge:`clang-format 18` :ref:`¶ <AllowShortCompoundRequirementOnASingleLine>`
- Allow short compound requirement on a single line.
+: If `true`, short case labels will be contracted to a single line.
- .. code-block:: c++
+ ```c++
+ true: false:
+ switch (a) { vs. switch (a) {
+ case 1: x = 1; break; case 1:
+ case 2: return; x = 1;
+ } break;
+ case 2:
+ return;
+ }
+ ```
- true:
- template <typename T>
- concept c = requires(T x) {
- { x + 1 } -> std::same_as<int>;
- };
+(allowshortcompoundrequirementonasingleline)=
- false:
- template <typename T>
- concept c = requires(T x) {
- {
- x + 1
- } -> std::same_as<int>;
- };
+**AllowShortCompoundRequirementOnASingleLine** (`Boolean`) {versionbadge}`clang-format 18` {ref}`¶ <AllowShortCompoundRequirementOnASingleLine>`
-.. _AllowShortEnumsOnASingleLine:
+: Allow short compound requirement on a single line.
-**AllowShortEnumsOnASingleLine** (``Boolean``) :versionbadge:`clang-format 11` :ref:`¶ <AllowShortEnumsOnASingleLine>`
- Allow short enums on a single line.
+ ```c++
+ true:
+ template <typename T>
+ concept c = requires(T x) {
+ { x + 1 } -> std::same_as<int>;
+ };
- .. code-block:: c++
+ false:
+ template <typename T>
+ concept c = requires(T x) {
+ {
+ x + 1
+ } -> std::same_as<int>;
+ };
+ ```
- true:
- enum { A, B } myEnum;
+(allowshortenumsonasingleline)=
- false:
- enum {
- A,
- B
- } myEnum;
+**AllowShortEnumsOnASingleLine** (`Boolean`) {versionbadge}`clang-format 11` {ref}`¶ <AllowShortEnumsOnASingleLine>`
+
+: Allow short enums on a single line.
+
+ ```c++
+ true:
+ enum { A, B } myEnum;
+
+ false:
+ enum {
+ A,
+ B
+ } myEnum;
+ ```
-.. _AllowShortFunctionsOnASingleLine:
+(allowshortfunctionsonasingleline)=
-**AllowShortFunctionsOnASingleLine** (``ShortFunctionStyle``) :versionbadge:`clang-format 3.5` :ref:`¶ <AllowShortFunctionsOnASingleLine>`
- Dependent on the value, ``int f() { return 0; }`` can be put on a
+**AllowShortFunctionsOnASingleLine** (`ShortFunctionStyle`) {versionbadge}`clang-format 3.5` {ref}`¶ <AllowShortFunctionsOnASingleLine>`
+
+: Dependent on the value, `int f() { return 0; }` can be put on a
single line.
Nested configuration flags:
@@ -1941,2507 +1944,2565 @@ the configuration (without a prefix: ``Auto``).
They can be read as a whole for compatibility. The choices are:
- * ``None``
+ - `None`
Never merge functions into a single line.
- * ``InlineOnly``
- Only merge functions defined inside a class. Same as ``inline``,
- except it does not implies ``empty``: i.e. top level empty functions
- are not merged either. See ``Inline`` of ``ShortFunctionStyle``.
-
- .. code-block:: c++
-
- class Foo {
- void f() { foo(); }
- };
- void f() {
- foo();
- }
- void f() {
- }
-
- * ``Empty``
- Only merge empty functions. See ``Empty`` of ``ShortFunctionStyle``.
+ - `InlineOnly`
+ Only merge functions defined inside a class. Same as `inline`,
+ except it does not implies `empty`: i.e. top level empty functions
+ are not merged either. See `Inline` of `ShortFunctionStyle`.
- .. code-block:: c++
+ ```c++
+ class Foo {
+ void f() { foo(); }
+ };
+ void f() {
+ foo();
+ }
+ void f() {
+ }
+ ```
- void f() {}
- void f2() {
- bar2();
- }
+ - `Empty`
+ Only merge empty functions. See `Empty` of `ShortFunctionStyle`.
- * ``Inline``
- Only merge functions defined inside a class. Implies ``empty``. See
- ``Inline`` and ``Empty`` of ``ShortFunctionStyle``.
+ ```c++
+ void f() {}
+ void f2() {
+ bar2();
+ }
+ ```
- .. code-block:: c++
+ - `Inline`
+ Only merge functions defined inside a class. Implies `empty`. See
+ `Inline` and `Empty` of `ShortFunctionStyle`.
- class Foo {
- void f() { foo(); }
- };
- void f() {
- foo();
- }
- void f() {}
+ ```c++
+ class Foo {
+ void f() { foo(); }
+ };
+ void f() {
+ foo();
+ }
+ void f() {}
+ ```
- * ``All``
+ - `All`
Merge all functions fitting on a single line.
- .. code-block:: c++
-
- class Foo {
- void f() { foo(); }
- };
- void f() { bar(); }
+ ```c++
+ class Foo {
+ void f() { foo(); }
+ };
+ void f() { bar(); }
+ ```
Also can be specified as a nested configuration flag:
- .. code-block:: c++
-
- # Example of usage:
- AllowShortFunctionsOnASingleLine: InlineOnly
+ ```yaml
+ # Example of usage:
+ AllowShortFunctionsOnASingleLine: InlineOnly
- # or more granular control:
- AllowShortFunctionsOnASingleLine:
- Empty: false
- Inline: true
- Other: false
+ # or more granular control:
+ AllowShortFunctionsOnASingleLine:
+ Empty: false
+ Inline: true
+ Other: false
+ ```
- * ``bool Empty`` Merge top-level empty functions.
+ - `bool Empty` Merge top-level empty functions.
- .. code-block:: c++
-
- void f() {}
- void f2() {
- bar2();
- }
- void f3() { /* comment */ }
-
- * ``bool Inline`` Merge functions defined inside a class.
+ ```c++
+ void f() {}
+ void f2() {
+ bar2();
+ }
+ void f3() { /* comment */ }
+ ```
- .. code-block:: c++
+ - `bool Inline` Merge functions defined inside a class.
- class Foo {
- void f() { foo(); }
- void g() {}
- };
- void f() {
- foo();
- }
- void f() {
- }
+ ```c++
+ class Foo {
+ void f() { foo(); }
+ void g() {}
+ };
+ void f() {
+ foo();
+ }
+ void f() {
+ }
+ ```
- * ``bool Other`` Merge all functions fitting on a single line. Please note that this
+ - `bool Other` Merge all functions fitting on a single line. Please note that this
control does not include Empty
- .. code-block:: c++
+ ```c++
+ class Foo {
+ void f() { foo(); }
+ };
+ void f() { bar(); }
+ ```
- class Foo {
- void f() { foo(); }
- };
- void f() { bar(); }
+(allowshortifstatementsonasingleline)=
-.. _AllowShortIfStatementsOnASingleLine:
+**AllowShortIfStatementsOnASingleLine** (`ShortIfStyle`) {versionbadge}`clang-format 3.3` {ref}`¶ <AllowShortIfStatementsOnASingleLine>`
-**AllowShortIfStatementsOnASingleLine** (``ShortIfStyle``) :versionbadge:`clang-format 3.3` :ref:`¶ <AllowShortIfStatementsOnASingleLine>`
- Dependent on the value, ``if (a) return;`` can be put on a single line.
+: Dependent on the value, `if (a) return;` can be put on a single line.
Possible values:
- * ``SIS_Never`` (in configuration: ``Never``)
+ - `SIS_Never` (in configuration: `Never`)
Never put short ifs on the same line.
- .. code-block:: c++
-
- if (a)
- return;
+ ```c++
+ if (a)
+ return;
- if (b)
- return;
- else
- return;
+ if (b)
+ return;
+ else
+ return;
- if (c)
- return;
- else {
- return;
- }
+ if (c)
+ return;
+ else {
+ return;
+ }
+ ```
- * ``SIS_WithoutElse`` (in configuration: ``WithoutElse``)
+ - `SIS_WithoutElse` (in configuration: `WithoutElse`)
Put short ifs on the same line only if there is no else statement.
- .. code-block:: c++
-
- if (a) return;
+ ```c++
+ if (a) return;
- if (b)
- return;
- else
- return;
+ if (b)
+ return;
+ else
+ return;
- if (c)
- return;
- else {
- return;
- }
+ if (c)
+ return;
+ else {
+ return;
+ }
+ ```
- * ``SIS_OnlyFirstIf`` (in configuration: ``OnlyFirstIf``)
+ - `SIS_OnlyFirstIf` (in configuration: `OnlyFirstIf`)
Put short ifs, but not else ifs nor else statements, on the same line.
- .. code-block:: c++
-
- if (a) return;
+ ```c++
+ if (a) return;
- if (b) return;
- else if (b)
- return;
- else
- return;
+ if (b) return;
+ else if (b)
+ return;
+ else
+ return;
- if (c) return;
- else {
- return;
- }
+ if (c) return;
+ else {
+ return;
+ }
+ ```
- * ``SIS_AllIfsAndElse`` (in configuration: ``AllIfsAndElse``)
+ - `SIS_AllIfsAndElse` (in configuration: `AllIfsAndElse`)
Always put short ifs, else ifs and else statements on the same
line.
- .. code-block:: c++
+ ```c++
+ if (a) return;
- if (a) return;
+ if (b) return;
+ else return;
- if (b) return;
- else return;
+ if (c) return;
+ else {
+ return;
+ }
+ ```
- if (c) return;
- else {
- return;
- }
+(allowshortlambdasonasingleline)=
-.. _AllowShortLambdasOnASingleLine:
+**AllowShortLambdasOnASingleLine** (`ShortLambdaStyle`) {versionbadge}`clang-format 9` {ref}`¶ <AllowShortLambdasOnASingleLine>`
-**AllowShortLambdasOnASingleLine** (``ShortLambdaStyle``) :versionbadge:`clang-format 9` :ref:`¶ <AllowShortLambdasOnASingleLine>`
- Dependent on the value, ``auto lambda []() { return 0; }`` can be put on a
+: Dependent on the value, `auto lambda []() { return 0; }` can be put on a
single line.
Possible values:
- * ``SLS_None`` (in configuration: ``None``)
+ - `SLS_None` (in configuration: `None`)
Never merge lambdas into a single line.
- * ``SLS_Empty`` (in configuration: ``Empty``)
+ - `SLS_Empty` (in configuration: `Empty`)
Only merge empty lambdas.
- .. code-block:: c++
-
- auto lambda = [](int a) {};
- auto lambda2 = [](int a) {
- return a;
- };
+ ```c++
+ auto lambda = [](int a) {};
+ auto lambda2 = [](int a) {
+ return a;
+ };
+ ```
- * ``SLS_Inline`` (in configuration: ``Inline``)
+ - `SLS_Inline` (in configuration: `Inline`)
Merge lambda into a single line if the lambda is argument of a function.
- .. code-block:: c++
-
- auto lambda = [](int x, int y) {
- return x < y;
- };
- sort(a.begin(), a.end(), [](int x, int y) { return x < y; });
+ ```c++
+ auto lambda = [](int x, int y) {
+ return x < y;
+ };
+ sort(a.begin(), a.end(), [](int x, int y) { return x < y; });
+ ```
- * ``SLS_All`` (in configuration: ``All``)
+ - `SLS_All` (in configuration: `All`)
Merge all lambdas fitting on a single line.
- .. code-block:: c++
+ ```c++
+ auto lambda = [](int a) {};
+ auto lambda2 = [](int a) { return a; };
+ ```
- auto lambda = [](int a) {};
- auto lambda2 = [](int a) { return a; };
+(allowshortloopsonasingleline)=
-.. _AllowShortLoopsOnASingleLine:
+**AllowShortLoopsOnASingleLine** (`Boolean`) {versionbadge}`clang-format 3.7` {ref}`¶ <AllowShortLoopsOnASingleLine>`
-**AllowShortLoopsOnASingleLine** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <AllowShortLoopsOnASingleLine>`
- If ``true``, ``while (true) continue;`` can be put on a single
+: If `true`, `while (true) continue;` can be put on a single
line.
-.. _AllowShortNamespacesOnASingleLine:
+(allowshortnamespacesonasingleline)=
+
+**AllowShortNamespacesOnASingleLine** (`Boolean`) {versionbadge}`clang-format 20` {ref}`¶ <AllowShortNamespacesOnASingleLine>`
-**AllowShortNamespacesOnASingleLine** (``Boolean``) :versionbadge:`clang-format 20` :ref:`¶ <AllowShortNamespacesOnASingleLine>`
- If ``true``, ``namespace a { class b; }`` can be put on a single line.
+: If `true`, `namespace a { class b; }` can be put on a single line.
-.. _AllowShortRecordOnASingleLine:
+(allowshortrecordonasingleline)=
-**AllowShortRecordOnASingleLine** (``ShortRecordStyle``) :versionbadge:`clang-format 23` :ref:`¶ <AllowShortRecordOnASingleLine>`
- Dependent on the value, ``struct bar { int i; };`` can be put on a single
+**AllowShortRecordOnASingleLine** (`ShortRecordStyle`) {versionbadge}`clang-format 23` {ref}`¶ <AllowShortRecordOnASingleLine>`
+
+: Dependent on the value, `struct bar { int i; };` can be put on a single
line.
Possible values:
- * ``SRS_Never`` (in configuration: ``Never``)
+ - `SRS_Never` (in configuration: `Never`)
Never merge records into a single line.
- * ``SRS_EmptyAndAttached`` (in configuration: ``EmptyAndAttached``)
+ - `SRS_EmptyAndAttached` (in configuration: `EmptyAndAttached`)
Only merge empty records if the opening brace was not wrapped,
- i.e. the corresponding ``BraceWrapping.After...`` option was not set.
+ i.e. the corresponding `BraceWrapping.After...` option was not set.
- * ``SRS_Empty`` (in configuration: ``Empty``)
+ - `SRS_Empty` (in configuration: `Empty`)
Only merge empty records.
- .. code-block:: c++
-
- struct foo {};
- struct bar
- {
- int i;
- };
+ ```c++
+ struct foo {};
+ struct bar
+ {
+ int i;
+ };
+ ```
- * ``SRS_Always`` (in configuration: ``Always``)
+ - `SRS_Always` (in configuration: `Always`)
Merge all records that fit on a single line.
- .. code-block:: c++
+ ```c++
+ struct foo {};
+ struct bar { int i; };
+ ```
- struct foo {};
- struct bar { int i; };
+(alwaysbreakafterdefinitionreturntype)=
-.. _AlwaysBreakAfterDefinitionReturnType:
+**AlwaysBreakAfterDefinitionReturnType** (`DefinitionReturnTypeBreakingStyle`) {versionbadge}`clang-format 3.7` {ref}`¶ <AlwaysBreakAfterDefinitionReturnType>`
-**AlwaysBreakAfterDefinitionReturnType** (``DefinitionReturnTypeBreakingStyle``) :versionbadge:`clang-format 3.7` :ref:`¶ <AlwaysBreakAfterDefinitionReturnType>`
- The function definition return type breaking style to use. This
+: The function definition return type breaking style to use. This
option is **deprecated** and is retained for backwards compatibility.
Possible values:
- * ``DRTBS_None`` (in configuration: ``None``)
+ - `DRTBS_None` (in configuration: `None`)
Break after return type automatically.
- ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
+ `PenaltyReturnTypeOnItsOwnLine` is taken into account.
- * ``DRTBS_All`` (in configuration: ``All``)
+ - `DRTBS_All` (in configuration: `All`)
Always break after the return type.
- * ``DRTBS_TopLevel`` (in configuration: ``TopLevel``)
+ - `DRTBS_TopLevel` (in configuration: `TopLevel`)
Always break after the return types of top-level functions.
-.. _AlwaysBreakAfterReturnType:
+(alwaysbreakafterreturntype)=
+
+**AlwaysBreakAfterReturnType** (`deprecated`) {versionbadge}`clang-format 3.8` {ref}`¶ <AlwaysBreakAfterReturnType>`
+
+: This option is renamed to `BreakAfterReturnType`.
-**AlwaysBreakAfterReturnType** (``deprecated``) :versionbadge:`clang-format 3.8` :ref:`¶ <AlwaysBreakAfterReturnType>`
- This option is renamed to ``BreakAfterReturnType``.
+(alwaysbreakbeforemultilinestrings)=
-.. _AlwaysBreakBeforeMultilineStrings:
+**AlwaysBreakBeforeMultilineStrings** (`Boolean`) {versionbadge}`clang-format 3.4` {ref}`¶ <AlwaysBreakBeforeMultilineStrings>`
-**AlwaysBreakBeforeMultilineStrings** (``Boolean``) :versionbadge:`clang-format 3.4` :ref:`¶ <AlwaysBreakBeforeMultilineStrings>`
- If ``true``, always break before multiline string literals.
+: If `true`, always break before multiline string literals.
This flag is mean to make cases where there are multiple multiline strings
in a file look more consistent. Thus, it will only take effect if wrapping
the string at that point leads to it being indented
- ``ContinuationIndentWidth`` spaces from the start of the line.
+ `ContinuationIndentWidth` spaces from the start of the line.
- .. code-block:: c++
+ ```c++
+ true: false:
+ aaaa = vs. aaaa = "bbbb"
+ "bbbb" "cccc";
+ "cccc";
+ ```
- true: false:
- aaaa = vs. aaaa = "bbbb"
- "bbbb" "cccc";
- "cccc";
+(alwaysbreaktemplatedeclarations)=
-.. _AlwaysBreakTemplateDeclarations:
+**AlwaysBreakTemplateDeclarations** (`deprecated`) {versionbadge}`clang-format 3.4` {ref}`¶ <AlwaysBreakTemplateDeclarations>`
-**AlwaysBreakTemplateDeclarations** (``deprecated``) :versionbadge:`clang-format 3.4` :ref:`¶ <AlwaysBreakTemplateDeclarations>`
- This option is renamed to ``BreakTemplateDeclarations``.
+: This option is renamed to `BreakTemplateDeclarations`.
-.. _AttributeMacros:
+(attributemacros)=
-**AttributeMacros** (``List of Strings``) :versionbadge:`clang-format 12` :ref:`¶ <AttributeMacros>`
- A vector of strings that should be interpreted as attributes/qualifiers
+**AttributeMacros** (`List of Strings`) {versionbadge}`clang-format 12` {ref}`¶ <AttributeMacros>`
+
+: A vector of strings that should be interpreted as attributes/qualifiers
instead of identifiers. This can be useful for language extensions or
static analyzer annotations.
For example:
- .. code-block:: c++
-
- x = (char *__capability)&y;
- int function(void) __unused;
- void only_writes_to_buffer(char *__output buffer);
+ ```c++
+ x = (char *__capability)&y;
+ int function(void) __unused;
+ void only_writes_to_buffer(char *__output buffer);
+ ```
In the .clang-format configuration file, this can be configured like:
- .. code-block:: yaml
+ ```yaml
+ AttributeMacros: [__capability, __output, __unused]
+ ```
- AttributeMacros: [__capability, __output, __unused]
+(binpackarguments)=
-.. _BinPackArguments:
+**BinPackArguments** (`Boolean`) {versionbadge}`clang-format 3.7` {ref}`¶ <BinPackArguments>`
-**BinPackArguments** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <BinPackArguments>`
- This option is **deprecated**. See ``BinPack`` of ``PackArguments``.
+: This option is **deprecated**. See `BinPack` of `PackArguments`.
-.. _BinPackLongBracedList:
+(binpacklongbracedlist)=
-**BinPackLongBracedList** (``Boolean``) :versionbadge:`clang-format 21` :ref:`¶ <BinPackLongBracedList>`
- If ``BinPackLongBracedList`` is ``true`` it overrides
- ``BinPackArguments`` if there are 20 or more items in a braced
+**BinPackLongBracedList** (`Boolean`) {versionbadge}`clang-format 21` {ref}`¶ <BinPackLongBracedList>`
+
+: If `BinPackLongBracedList` is `true` it overrides
+ `BinPackArguments` if there are 20 or more items in a braced
initializer list.
- .. code-block:: c++
+ ```c++
+ BinPackLongBracedList: false vs. BinPackLongBracedList: true
+ vector<int> x{ vector<int> x{1, 2, ...,
+ 20, 21};
+ 1,
+ 2,
+ ...,
+ 20,
+ 21};
+ ```
- BinPackLongBracedList: false vs. BinPackLongBracedList: true
- vector<int> x{ vector<int> x{1, 2, ...,
- 20, 21};
- 1,
- 2,
- ...,
- 20,
- 21};
+(binpackparameters)=
-.. _BinPackParameters:
+**BinPackParameters** (`BinPackParametersStyle`) {versionbadge}`clang-format 3.7` {ref}`¶ <BinPackParameters>`
-**BinPackParameters** (``BinPackParametersStyle``) :versionbadge:`clang-format 3.7` :ref:`¶ <BinPackParameters>`
- This option is **deprecated**. See ``BinPack`` of ``PackParameters``.
+: This option is **deprecated**. See `BinPack` of `PackParameters`.
Possible values:
- * ``BPPS_BinPack`` (in configuration: ``BinPack``)
+ - `BPPS_BinPack` (in configuration: `BinPack`)
Bin-pack parameters.
- .. code-block:: c++
-
- void f(int a, int bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb,
- int ccccccccccccccccccccccccccccccccccccccccccc);
+ ```c++
+ void f(int a, int bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb,
+ int ccccccccccccccccccccccccccccccccccccccccccc);
+ ```
- * ``BPPS_OnePerLine`` (in configuration: ``OnePerLine``)
+ - `BPPS_OnePerLine` (in configuration: `OnePerLine`)
Put all parameters on the current line if they fit.
Otherwise, put each one on its own line.
- .. code-block:: c++
+ ```c++
+ void f(int a, int b, int c);
- void f(int a, int b, int c);
+ void f(int a,
+ int b,
+ int ccccccccccccccccccccccccccccccccccccc);
+ ```
- void f(int a,
- int b,
- int ccccccccccccccccccccccccccccccccccccc);
-
- * ``BPPS_AlwaysOnePerLine`` (in configuration: ``AlwaysOnePerLine``)
+ - `BPPS_AlwaysOnePerLine` (in configuration: `AlwaysOnePerLine`)
Always put each parameter on its own line.
- .. code-block:: c++
+ ```c++
+ void f(int a,
+ int b,
+ int c);
+ ```
- void f(int a,
- int b,
- int c);
+ - `BPPS_UseBreakAfter` (in configuration: `UseBreakAfter`)
+ Use the `BreakAfter` option to handle parameter packing instead.
+ If the `BreakAfter` limit is not exceeded, behave like `BinPack`.
- * ``BPPS_UseBreakAfter`` (in configuration: ``UseBreakAfter``)
- Use the ``BreakAfter`` option to handle parameter packing instead.
- If the ``BreakAfter`` limit is not exceeded, behave like ``BinPack``.
+(bitfieldcolonspacing)=
-.. _BitFieldColonSpacing:
+**BitFieldColonSpacing** (`BitFieldColonSpacingStyle`) {versionbadge}`clang-format 12` {ref}`¶ <BitFieldColonSpacing>`
-**BitFieldColonSpacing** (``BitFieldColonSpacingStyle``) :versionbadge:`clang-format 12` :ref:`¶ <BitFieldColonSpacing>`
- The BitFieldColonSpacingStyle to use for bitfields.
+: The BitFieldColonSpacingStyle to use for bitfields.
Possible values:
- * ``BFCS_Both`` (in configuration: ``Both``)
- Add one space on each side of the ``:``
-
- .. code-block:: c++
-
- unsigned bf : 2;
-
- * ``BFCS_None`` (in configuration: ``None``)
- Add no space around the ``:`` (except when needed for
- ``AlignConsecutiveBitFields``).
+ - `BFCS_Both` (in configuration: `Both`)
+ Add one space on each side of the `:`
- .. code-block:: c++
+ ```c++
+ unsigned bf : 2;
+ ```
- unsigned bf:2;
+ - `BFCS_None` (in configuration: `None`)
+ Add no space around the `:` (except when needed for
+ `AlignConsecutiveBitFields`).
- * ``BFCS_Before`` (in configuration: ``Before``)
- Add space before the ``:`` only
+ ```c++
+ unsigned bf:2;
+ ```
- .. code-block:: c++
+ - `BFCS_Before` (in configuration: `Before`)
+ Add space before the `:` only
- unsigned bf :2;
+ ```c++
+ unsigned bf :2;
+ ```
- * ``BFCS_After`` (in configuration: ``After``)
- Add space after the ``:`` only (space may be added before if
- needed for ``AlignConsecutiveBitFields``).
+ - `BFCS_After` (in configuration: `After`)
+ Add space after the `:` only (space may be added before if
+ needed for `AlignConsecutiveBitFields`).
- .. code-block:: c++
+ ```c++
+ unsigned bf: 2;
+ ```
- unsigned bf: 2;
+(bracewrapping)=
-.. _BraceWrapping:
+**BraceWrapping** (`BraceWrappingFlags`) {versionbadge}`clang-format 3.8` {ref}`¶ <BraceWrapping>`
-**BraceWrapping** (``BraceWrappingFlags``) :versionbadge:`clang-format 3.8` :ref:`¶ <BraceWrapping>`
- Control of individual brace wrapping cases.
+: Control of individual brace wrapping cases.
- If ``BreakBeforeBraces`` is set to ``Custom``, use this to specify how
+ If `BreakBeforeBraces` is set to `Custom`, use this to specify how
each individual brace case should be handled. Otherwise, this is ignored.
- .. code-block:: yaml
-
- # Example of usage:
- BreakBeforeBraces: Custom
- BraceWrapping:
- AfterEnum: true
- AfterStruct: false
- SplitEmptyFunction: false
+ ```yaml
+ # Example of usage:
+ BreakBeforeBraces: Custom
+ BraceWrapping:
+ AfterEnum: true
+ AfterStruct: false
+ SplitEmptyFunction: false
+ ```
Nested configuration flags:
Precise control over the wrapping of braces.
- .. code-block:: c++
+ ```yaml
+ # Should be declared this way:
+ BreakBeforeBraces: Custom
+ BraceWrapping:
+ AfterClass: true
+ ```
+
+ - `bool AfterCaseLabel` Wrap case labels.
+
+ ```c++
+ false: true:
+ switch (foo) { vs. switch (foo) {
+ case 1: { case 1:
+ bar(); {
+ break; bar();
+ } break;
+ default: { }
+ plop(); default:
+ } {
+ } plop();
+ }
+ }
+ ```
- # Should be declared this way:
- BreakBeforeBraces: Custom
- BraceWrapping:
- AfterClass: true
+ - `bool AfterClass` Wrap class definitions.
- * ``bool AfterCaseLabel`` Wrap case labels.
+ ```c++
+ true:
+ class foo
+ {};
- .. code-block:: c++
+ false:
+ class foo {};
+ ```
- false: true:
- switch (foo) { vs. switch (foo) {
- case 1: { case 1:
- bar(); {
- break; bar();
- } break;
- default: { }
- plop(); default:
- } {
- } plop();
- }
- }
+ - `BraceWrappingAfterControlStatementStyle AfterControlStatement`
+ Wrap control statements (`if`/`for`/`while`/`switch`/..).
- * ``bool AfterClass`` Wrap class definitions.
+ Possible values:
- .. code-block:: c++
+ - `BWACS_Never` (in configuration: `Never`)
+ Never wrap braces after a control statement.
- true:
- class foo
- {};
-
- false:
- class foo {};
-
- * ``BraceWrappingAfterControlStatementStyle AfterControlStatement``
- Wrap control statements (``if``/``for``/``while``/``switch``/..).
-
- Possible values:
-
- * ``BWACS_Never`` (in configuration: ``Never``)
- Never wrap braces after a control statement.
-
- .. code-block:: c++
-
- if (foo()) {
- } else {
- }
- for (int i = 0; i < 10; ++i) {
- }
+ ```c++
+ if (foo()) {
+ } else {
+ }
+ for (int i = 0; i < 10; ++i) {
+ }
+ ```
- * ``BWACS_MultiLine`` (in configuration: ``MultiLine``)
+ - `BWACS_MultiLine` (in configuration: `MultiLine`)
Only wrap braces after a multi-line control statement.
- .. code-block:: c++
-
- if (foo && bar &&
- baz)
- {
- quux();
- }
- while (foo || bar) {
- }
-
- * ``BWACS_Always`` (in configuration: ``Always``)
- Always wrap braces after a control statement.
-
- .. code-block:: c++
-
- if (foo())
- {
- } else
- {}
- for (int i = 0; i < 10; ++i)
- {}
-
-
- * ``bool AfterEnum`` Wrap enum definitions.
-
- .. code-block:: c++
-
- true:
- enum X : int
- {
- B
- };
-
- false:
- enum X : int { B };
-
- * ``bool AfterFunction`` Wrap function definitions.
-
- .. code-block:: c++
-
- true:
- void foo()
+ ```c++
+ if (foo && bar &&
+ baz)
{
- bar();
- bar2();
+ quux();
}
-
- false:
- void foo() {
- bar();
- bar2();
+ while (foo || bar) {
}
+ ```
- * ``bool AfterNamespace`` Wrap namespace definitions.
-
- .. code-block:: c++
+ - `BWACS_Always` (in configuration: `Always`)
+ Always wrap braces after a control statement.
- true:
- namespace
+ ```c++
+ if (foo())
{
- int foo();
- int bar();
- }
+ } else
+ {}
+ for (int i = 0; i < 10; ++i)
+ {}
+ ```
- false:
- namespace {
- int foo();
- int bar();
- }
- * ``bool AfterObjCDeclaration`` Wrap ObjC definitions (interfaces, implementations...).
+ - `bool AfterEnum` Wrap enum definitions.
- .. note::
+ ```c++
+ true:
+ enum X : int
+ {
+ B
+ };
- @autoreleasepool and @synchronized blocks are wrapped
- according to ``AfterControlStatement`` flag.
+ false:
+ enum X : int { B };
+ ```
- * ``bool AfterStruct`` Wrap struct definitions.
+ - `bool AfterFunction` Wrap function definitions.
- .. code-block:: c++
+ ```c++
+ true:
+ void foo()
+ {
+ bar();
+ bar2();
+ }
- true:
- struct foo
- {
- int x;
- };
+ false:
+ void foo() {
+ bar();
+ bar2();
+ }
+ ```
- false:
- struct foo {
- int x;
- };
+ - `bool AfterNamespace` Wrap namespace definitions.
- * ``bool AfterUnion`` Wrap union definitions.
+ ```c++
+ true:
+ namespace
+ {
+ int foo();
+ int bar();
+ }
- .. code-block:: c++
+ false:
+ namespace {
+ int foo();
+ int bar();
+ }
+ ```
- true:
- union foo
- {
- int x;
- }
+ - `bool AfterObjCDeclaration` Wrap ObjC definitions (interfaces, implementations...).
- false:
- union foo {
- int x;
- }
+ :::{note}
+ @autoreleasepool and @synchronized blocks are wrapped
+ according to `AfterControlStatement` flag.
+ :::
- * ``bool AfterExternBlock`` Wrap extern blocks.
+ - `bool AfterStruct` Wrap struct definitions.
- .. code-block:: c++
+ ```c++
+ true:
+ struct foo
+ {
+ int x;
+ };
- true:
- extern "C"
- {
- int foo();
- }
+ false:
+ struct foo {
+ int x;
+ };
+ ```
- false:
- extern "C" {
- int foo();
- }
+ - `bool AfterUnion` Wrap union definitions.
- * ``bool BeforeCatch`` Wrap before ``catch``.
+ ```c++
+ true:
+ union foo
+ {
+ int x;
+ }
- .. code-block:: c++
+ false:
+ union foo {
+ int x;
+ }
+ ```
- true:
- try {
- foo();
- }
- catch () {
- }
+ - `bool AfterExternBlock` Wrap extern blocks.
- false:
- try {
- foo();
- } catch () {
- }
+ ```c++
+ true:
+ extern "C"
+ {
+ int foo();
+ }
- * ``bool BeforeElse`` Wrap before ``else``.
+ false:
+ extern "C" {
+ int foo();
+ }
+ ```
- .. code-block:: c++
+ - `bool BeforeCatch` Wrap before `catch`.
- true:
- if (foo()) {
- }
- else {
- }
+ ```c++
+ true:
+ try {
+ foo();
+ }
+ catch () {
+ }
- false:
- if (foo()) {
- } else {
- }
+ false:
+ try {
+ foo();
+ } catch () {
+ }
+ ```
- * ``bool BeforeLambdaBody`` Wrap lambda block.
+ - `bool BeforeElse` Wrap before `else`.
- .. code-block:: c++
+ ```c++
+ true:
+ if (foo()) {
+ }
+ else {
+ }
- true:
- connect(
- []()
- {
- foo();
- bar();
- });
+ false:
+ if (foo()) {
+ } else {
+ }
+ ```
- false:
- connect([]() {
+ - `bool BeforeLambdaBody` Wrap lambda block.
+
+ ```c++
+ true:
+ connect(
+ []()
+ {
foo();
bar();
});
- * ``bool BeforeWhile`` Wrap before ``while``.
+ false:
+ connect([]() {
+ foo();
+ bar();
+ });
+ ```
- .. code-block:: c++
+ - `bool BeforeWhile` Wrap before `while`.
- true:
- do {
- foo();
- }
- while (1);
+ ```c++
+ true:
+ do {
+ foo();
+ }
+ while (1);
- false:
- do {
- foo();
- } while (1);
+ false:
+ do {
+ foo();
+ } while (1);
+ ```
- * ``bool IndentBraces`` Indent the wrapped braces themselves.
+ - `bool IndentBraces` Indent the wrapped braces themselves.
- * ``bool SplitEmptyFunction`` If ``false``, empty function body can be put on a single line.
+ - `bool SplitEmptyFunction` If `false`, empty function body can be put on a single line.
This option is used only if the opening brace of the function has
- already been wrapped, i.e. the ``AfterFunction`` brace wrapping mode is
+ already been wrapped, i.e. the `AfterFunction` brace wrapping mode is
set, and the function could/should not be put on a single line (as per
- ``AllowShortFunctionsOnASingleLine`` and constructor formatting
+ `AllowShortFunctionsOnASingleLine` and constructor formatting
options).
- .. code-block:: c++
-
- false: true:
- int f() vs. int f()
- {} {
- }
+ ```c++
+ false: true:
+ int f() vs. int f()
+ {} {
+ }
+ ```
- * ``bool SplitEmptyRecord`` If ``false``, empty record (e.g. class, struct or union) body
+ - `bool SplitEmptyRecord` If `false`, empty record (e.g. class, struct or union) body
can be put on a single line. This option is used only if the opening
- brace of the record has already been wrapped, i.e. the ``AfterClass``
+ brace of the record has already been wrapped, i.e. the `AfterClass`
(for classes) brace wrapping mode is set.
- .. code-block:: c++
+ ```c++
+ false: true:
+ class Foo vs. class Foo
+ {} {
+ }
+ ```
- false: true:
- class Foo vs. class Foo
- {} {
- }
-
- * ``bool SplitEmptyNamespace`` If ``false``, empty namespace body can be put on a single line.
+ - `bool SplitEmptyNamespace` If `false`, empty namespace body can be put on a single line.
This option is used only if the opening brace of the namespace has
- already been wrapped, i.e. the ``AfterNamespace`` brace wrapping mode is
+ already been wrapped, i.e. the `AfterNamespace` brace wrapping mode is
set.
- .. code-block:: c++
+ ```c++
+ false: true:
+ namespace Foo vs. namespace Foo
+ {} {
+ }
+ ```
- false: true:
- namespace Foo vs. namespace Foo
- {} {
- }
+(bracedinitializerindentwidth)=
-.. _BracedInitializerIndentWidth:
+**BracedInitializerIndentWidth** (`Integer`) {versionbadge}`clang-format 17` {ref}`¶ <BracedInitializerIndentWidth>`
-**BracedInitializerIndentWidth** (``Integer``) :versionbadge:`clang-format 17` :ref:`¶ <BracedInitializerIndentWidth>`
- The number of columns to use to indent the contents of braced init lists.
- If unset or negative, ``ContinuationIndentWidth`` is used.
+: The number of columns to use to indent the contents of braced init lists.
+ If unset or negative, `ContinuationIndentWidth` is used.
- .. code-block:: c++
+ ```c++
+ AlignAfterOpenBracket: AlwaysBreak
+ BracedInitializerIndentWidth: 2
- AlignAfterOpenBracket: AlwaysBreak
- BracedInitializerIndentWidth: 2
+ void f() {
+ SomeClass c{
+ "foo",
+ "bar",
+ "baz",
+ };
+ auto s = SomeStruct{
+ .foo = "foo",
+ .bar = "bar",
+ .baz = "baz",
+ };
+ SomeArrayT a[3] = {
+ {
+ foo,
+ bar,
+ },
+ {
+ foo,
+ bar,
+ },
+ SomeArrayT{},
+ };
+ }
+ ```
- void f() {
- SomeClass c{
- "foo",
- "bar",
- "baz",
- };
- auto s = SomeStruct{
- .foo = "foo",
- .bar = "bar",
- .baz = "baz",
- };
- SomeArrayT a[3] = {
- {
- foo,
- bar,
- },
- {
- foo,
- bar,
- },
- SomeArrayT{},
- };
- }
+(breakadjacentstringliterals)=
-.. _BreakAdjacentStringLiterals:
+**BreakAdjacentStringLiterals** (`Boolean`) {versionbadge}`clang-format 18` {ref}`¶ <BreakAdjacentStringLiterals>`
-**BreakAdjacentStringLiterals** (``Boolean``) :versionbadge:`clang-format 18` :ref:`¶ <BreakAdjacentStringLiterals>`
- Break between adjacent string literals.
+: Break between adjacent string literals.
- .. code-block:: c++
+ ```c++
+ true:
+ return "Code"
+ "\0\52\26\55\55\0"
+ "x013"
+ "\02\xBA";
+ false:
+ return "Code" "\0\52\26\55\55\0" "x013" "\02\xBA";
+ ```
- true:
- return "Code"
- "\0\52\26\55\55\0"
- "x013"
- "\02\xBA";
- false:
- return "Code" "\0\52\26\55\55\0" "x013" "\02\xBA";
+(breakafterattributes)=
-.. _BreakAfterAttributes:
+**BreakAfterAttributes** (`AttributeBreakingStyle`) {versionbadge}`clang-format 16` {ref}`¶ <BreakAfterAttributes>`
-**BreakAfterAttributes** (``AttributeBreakingStyle``) :versionbadge:`clang-format 16` :ref:`¶ <BreakAfterAttributes>`
- Break after a group of C++11 attributes before variable or function
+: Break after a group of C++11 attributes before variable or function
(including constructor/destructor) declaration/definition names or before
- control statements, i.e. ``if``, ``switch`` (including ``case`` and
- ``default`` labels), ``for``, and ``while`` statements.
+ control statements, i.e. `if`, `switch` (including `case` and
+ `default` labels), `for`, and `while` statements.
Possible values:
- * ``ABS_Always`` (in configuration: ``Always``)
+ - `ABS_Always` (in configuration: `Always`)
Always break after the last attribute of the group.
- .. code-block:: c++
-
- [[maybe_unused]]
- const int i;
- [[gnu::const]] [[maybe_unused]]
- int j;
-
- [[nodiscard]]
- inline int f();
- [[gnu::const]] [[nodiscard]]
- int g();
+ ```c++
+ [[maybe_unused]]
+ const int i;
+ [[gnu::const]] [[maybe_unused]]
+ int j;
- [[likely]]
- if (a)
- f();
- else
- g();
+ [[nodiscard]]
+ inline int f();
+ [[gnu::const]] [[nodiscard]]
+ int g();
- switch (b) {
- [[unlikely]]
- case 1:
- ++b;
- break;
- [[likely]]
- default:
- return;
- }
+ [[likely]]
+ if (a)
+ f();
+ else
+ g();
+
+ switch (b) {
+ [[unlikely]]
+ case 1:
+ ++b;
+ break;
+ [[likely]]
+ default:
+ return;
+ }
+ ```
- * ``ABS_Leave`` (in configuration: ``Leave``)
+ - `ABS_Leave` (in configuration: `Leave`)
Leave the line breaking after the last attribute of the group as is.
- .. code-block:: c++
-
- [[maybe_unused]] const int i;
- [[gnu::const]] [[maybe_unused]]
- int j;
-
- [[nodiscard]] inline int f();
- [[gnu::const]] [[nodiscard]]
- int g();
+ ```c++
+ [[maybe_unused]] const int i;
+ [[gnu::const]] [[maybe_unused]]
+ int j;
- [[likely]] if (a)
- f();
- else
- g();
-
- switch (b) {
- [[unlikely]] case 1:
- ++b;
- break;
- [[likely]]
- default:
- return;
- }
+ [[nodiscard]] inline int f();
+ [[gnu::const]] [[nodiscard]]
+ int g();
- * ``ABS_LeaveAll`` (in configuration: ``LeaveAll``)
- Same as ``Leave`` except that it applies to all attributes of the group.
+ [[likely]] if (a)
+ f();
+ else
+ g();
+
+ switch (b) {
+ [[unlikely]] case 1:
+ ++b;
+ break;
+ [[likely]]
+ default:
+ return;
+ }
+ ```
- .. code-block:: c++
+ - `ABS_LeaveAll` (in configuration: `LeaveAll`)
+ Same as `Leave` except that it applies to all attributes of the group.
- [[deprecated("Don't use this version")]]
- [[nodiscard]]
- bool foo() {
- return true;
- }
+ ```c++
+ [[deprecated("Don't use this version")]]
+ [[nodiscard]]
+ bool foo() {
+ return true;
+ }
- [[deprecated("Don't use this version")]]
- [[nodiscard]] bool bar() {
- return true;
- }
+ [[deprecated("Don't use this version")]]
+ [[nodiscard]] bool bar() {
+ return true;
+ }
+ ```
- * ``ABS_Never`` (in configuration: ``Never``)
+ - `ABS_Never` (in configuration: `Never`)
Never break after the last attribute of the group.
- .. code-block:: c++
+ ```c++
+ [[maybe_unused]] const int i;
+ [[gnu::const]] [[maybe_unused]] int j;
- [[maybe_unused]] const int i;
- [[gnu::const]] [[maybe_unused]] int j;
+ [[nodiscard]] inline int f();
+ [[gnu::const]] [[nodiscard]] int g();
- [[nodiscard]] inline int f();
- [[gnu::const]] [[nodiscard]] int g();
+ [[likely]] if (a)
+ f();
+ else
+ g();
+
+ switch (b) {
+ [[unlikely]] case 1:
+ ++b;
+ break;
+ [[likely]] default:
+ return;
+ }
+ ```
- [[likely]] if (a)
- f();
- else
- g();
-
- switch (b) {
- [[unlikely]] case 1:
- ++b;
- break;
- [[likely]] default:
- return;
- }
+(breakafterjavafieldannotations)=
-.. _BreakAfterJavaFieldAnnotations:
+**BreakAfterJavaFieldAnnotations** (`Boolean`) {versionbadge}`clang-format 3.8` {ref}`¶ <BreakAfterJavaFieldAnnotations>`
-**BreakAfterJavaFieldAnnotations** (``Boolean``) :versionbadge:`clang-format 3.8` :ref:`¶ <BreakAfterJavaFieldAnnotations>`
- Break after each annotation on a field in Java files.
+: Break after each annotation on a field in Java files.
- .. code-block:: java
+ ```java
+ true: false:
+ @Partial vs. @Partial @Mock DataLoad loader;
+ @Mock
+ DataLoad loader;
+ ```
- true: false:
- @Partial vs. @Partial @Mock DataLoad loader;
- @Mock
- DataLoad loader;
+(breakafteropenbracketbracedlist)=
-.. _BreakAfterOpenBracketBracedList:
+**BreakAfterOpenBracketBracedList** (`Boolean`) {versionbadge}`clang-format 22` {ref}`¶ <BreakAfterOpenBracketBracedList>`
-**BreakAfterOpenBracketBracedList** (``Boolean``) :versionbadge:`clang-format 22` :ref:`¶ <BreakAfterOpenBracketBracedList>`
- Force break after the left bracket of a braced initializer list (when
- ``Cpp11BracedListStyle`` is ``true``) when the list exceeds the column
+: Force break after the left bracket of a braced initializer list (when
+ `Cpp11BracedListStyle` is `true`) when the list exceeds the column
limit.
- .. code-block:: c++
+ ```c++
+ true: false:
+ vector<int> x { vs. vector<int> x {1,
+ 1, 2, 3} 2, 3}
+ ```
- true: false:
- vector<int> x { vs. vector<int> x {1,
- 1, 2, 3} 2, 3}
+(breakafteropenbracketfunction)=
-.. _BreakAfterOpenBracketFunction:
+**BreakAfterOpenBracketFunction** (`Boolean`) {versionbadge}`clang-format 22` {ref}`¶ <BreakAfterOpenBracketFunction>`
-**BreakAfterOpenBracketFunction** (``Boolean``) :versionbadge:`clang-format 22` :ref:`¶ <BreakAfterOpenBracketFunction>`
- Force break after the left parenthesis of a function (declaration,
+: Force break after the left parenthesis of a function (declaration,
definition, call) when the parameters exceed the column limit.
- .. code-block:: c++
+ ```c++
+ true: false:
+ foo ( vs. foo (a,
+ a , b) b)
+ ```
- true: false:
- foo ( vs. foo (a,
- a , b) b)
+(breakafteropenbracketif)=
-.. _BreakAfterOpenBracketIf:
+**BreakAfterOpenBracketIf** (`Boolean`) {versionbadge}`clang-format 22` {ref}`¶ <BreakAfterOpenBracketIf>`
-**BreakAfterOpenBracketIf** (``Boolean``) :versionbadge:`clang-format 22` :ref:`¶ <BreakAfterOpenBracketIf>`
- Force break after the left parenthesis of an if control statement
+: Force break after the left parenthesis of an if control statement
when the expression exceeds the column limit.
- .. code-block:: c++
+ ```c++
+ true: false:
+ if constexpr ( vs. if constexpr (a ||
+ a || b) b)
+ ```
- true: false:
- if constexpr ( vs. if constexpr (a ||
- a || b) b)
+(breakafteropenbracketloop)=
-.. _BreakAfterOpenBracketLoop:
+**BreakAfterOpenBracketLoop** (`Boolean`) {versionbadge}`clang-format 22` {ref}`¶ <BreakAfterOpenBracketLoop>`
-**BreakAfterOpenBracketLoop** (``Boolean``) :versionbadge:`clang-format 22` :ref:`¶ <BreakAfterOpenBracketLoop>`
- Force break after the left parenthesis of a loop control statement
+: Force break after the left parenthesis of a loop control statement
when the expression exceeds the column limit.
- .. code-block:: c++
+ ```c++
+ true: false:
+ while ( vs. while (a &&
+ a && b) { b) {
+ ```
- true: false:
- while ( vs. while (a &&
- a && b) { b) {
+(breakafteropenbracketswitch)=
-.. _BreakAfterOpenBracketSwitch:
+**BreakAfterOpenBracketSwitch** (`Boolean`) {versionbadge}`clang-format 22` {ref}`¶ <BreakAfterOpenBracketSwitch>`
-**BreakAfterOpenBracketSwitch** (``Boolean``) :versionbadge:`clang-format 22` :ref:`¶ <BreakAfterOpenBracketSwitch>`
- Force break after the left parenthesis of a switch control statement
+: Force break after the left parenthesis of a switch control statement
when the expression exceeds the column limit.
- .. code-block:: c++
+ ```c++
+ true: false:
+ switch ( vs. switch (a +
+ a + b) { b) {
+ ```
- true: false:
- switch ( vs. switch (a +
- a + b) { b) {
+(breakafterreturntype)=
-.. _BreakAfterReturnType:
+**BreakAfterReturnType** (`ReturnTypeBreakingStyle`) {versionbadge}`clang-format 19` {ref}`¶ <BreakAfterReturnType>`
-**BreakAfterReturnType** (``ReturnTypeBreakingStyle``) :versionbadge:`clang-format 19` :ref:`¶ <BreakAfterReturnType>`
- The function declaration return type breaking style to use.
+: The function declaration return type breaking style to use.
Possible values:
- * ``RTBS_None`` (in configuration: ``None``)
- This is **deprecated**. See ``Automatic`` below.
+ - `RTBS_None` (in configuration: `None`)
+ This is **deprecated**. See `Automatic` below.
- * ``RTBS_Automatic`` (in configuration: ``Automatic``)
- Break after return type based on ``PenaltyReturnTypeOnItsOwnLine``.
+ - `RTBS_Automatic` (in configuration: `Automatic`)
+ Break after return type based on `PenaltyReturnTypeOnItsOwnLine`.
- .. code-block:: c++
-
- class A {
- int f() { return 0; };
- };
- int f();
- int f() { return 1; }
- int
- LongName::AnotherLongName();
-
- * ``RTBS_ExceptShortType`` (in configuration: ``ExceptShortType``)
- Same as ``Automatic`` above, except that there is no break after short
+ ```c++
+ class A {
+ int f() { return 0; };
+ };
+ int f();
+ int f() { return 1; }
+ int
+ LongName::AnotherLongName();
+ ```
+
+ - `RTBS_ExceptShortType` (in configuration: `ExceptShortType`)
+ Same as `Automatic` above, except that there is no break after short
return types.
- .. code-block:: c++
-
- class A {
- int f() { return 0; };
- };
- int f();
- int f() { return 1; }
- int LongName::
- AnotherLongName();
+ ```c++
+ class A {
+ int f() { return 0; };
+ };
+ int f();
+ int f() { return 1; }
+ int LongName::
+ AnotherLongName();
+ ```
- * ``RTBS_All`` (in configuration: ``All``)
+ - `RTBS_All` (in configuration: `All`)
Always break after the return type.
- .. code-block:: c++
-
- class A {
- int
- f() {
- return 0;
- };
- };
- int
- f();
+ ```c++
+ class A {
int
f() {
- return 1;
- }
- int
- LongName::AnotherLongName();
+ return 0;
+ };
+ };
+ int
+ f();
+ int
+ f() {
+ return 1;
+ }
+ int
+ LongName::AnotherLongName();
+ ```
- * ``RTBS_TopLevel`` (in configuration: ``TopLevel``)
+ - `RTBS_TopLevel` (in configuration: `TopLevel`)
Always break after the return types of top-level functions.
- .. code-block:: c++
-
- class A {
- int f() { return 0; };
- };
- int
- f();
- int
- f() {
- return 1;
- }
- int
- LongName::AnotherLongName();
+ ```c++
+ class A {
+ int f() { return 0; };
+ };
+ int
+ f();
+ int
+ f() {
+ return 1;
+ }
+ int
+ LongName::AnotherLongName();
+ ```
- * ``RTBS_AllDefinitions`` (in configuration: ``AllDefinitions``)
+ - `RTBS_AllDefinitions` (in configuration: `AllDefinitions`)
Always break after the return type of function definitions.
- .. code-block:: c++
-
- class A {
- int
- f() {
- return 0;
- };
- };
- int f();
+ ```c++
+ class A {
int
f() {
- return 1;
- }
- int
- LongName::AnotherLongName();
+ return 0;
+ };
+ };
+ int f();
+ int
+ f() {
+ return 1;
+ }
+ int
+ LongName::AnotherLongName();
+ ```
- * ``RTBS_TopLevelDefinitions`` (in configuration: ``TopLevelDefinitions``)
+ - `RTBS_TopLevelDefinitions` (in configuration: `TopLevelDefinitions`)
Always break after the return type of top-level definitions.
- .. code-block:: c++
+ ```c++
+ class A {
+ int f() { return 0; };
+ };
+ int f();
+ int
+ f() {
+ return 1;
+ }
+ int
+ LongName::AnotherLongName();
+ ```
- class A {
- int f() { return 0; };
- };
- int f();
- int
- f() {
- return 1;
- }
- int
- LongName::AnotherLongName();
+(breakarrays)=
-.. _BreakArrays:
+**BreakArrays** (`Boolean`) {versionbadge}`clang-format 16` {ref}`¶ <BreakArrays>`
-**BreakArrays** (``Boolean``) :versionbadge:`clang-format 16` :ref:`¶ <BreakArrays>`
- If ``true``, clang-format will always break after a Json array ``[``
- otherwise it will scan until the closing ``]`` to determine if it should
+: If `true`, clang-format will always break after a Json array `[`
+ otherwise it will scan until the closing `]` to determine if it should
add newlines between elements (prettier compatible).
+ :::{note}
+ This is currently only for formatting JSON.
+ :::
- .. note::
-
- This is currently only for formatting JSON.
+ ```c++
+ true: false:
+ [ vs. [1, 2, 3, 4]
+ 1,
+ 2,
+ 3,
+ 4
+ ]
+ ```
- .. code-block:: c++
+(breakbeforebinaryoperators)=
- true: false:
- [ vs. [1, 2, 3, 4]
- 1,
- 2,
- 3,
- 4
- ]
+**BreakBeforeBinaryOperators** (`BinaryOperatorStyle`) {versionbadge}`clang-format 3.6` {ref}`¶ <BreakBeforeBinaryOperators>`
-.. _BreakBeforeBinaryOperators:
-
-**BreakBeforeBinaryOperators** (``BinaryOperatorStyle``) :versionbadge:`clang-format 3.6` :ref:`¶ <BreakBeforeBinaryOperators>`
- The way to wrap binary operators.
+: The way to wrap binary operators.
Possible values:
- * ``BOS_None`` (in configuration: ``None``)
+ - `BOS_None` (in configuration: `None`)
Break after operators.
- .. code-block:: c++
-
- LooooooooooongType loooooooooooooooooooooongVariable =
- someLooooooooooooooooongFunction();
+ ```c++
+ LooooooooooongType loooooooooooooooooooooongVariable =
+ someLooooooooooooooooongFunction();
- bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +
- aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa ==
- aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa &&
- aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa >
- ccccccccccccccccccccccccccccccccccccccccc;
+ bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa +
+ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa ==
+ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa &&
+ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa >
+ ccccccccccccccccccccccccccccccccccccccccc;
+ ```
- * ``BOS_NonAssignment`` (in configuration: ``NonAssignment``)
+ - `BOS_NonAssignment` (in configuration: `NonAssignment`)
Break before operators that aren't assignments.
- .. code-block:: c++
-
- LooooooooooongType loooooooooooooooooooooongVariable =
- someLooooooooooooooooongFunction();
+ ```c++
+ LooooooooooongType loooooooooooooooooooooongVariable =
+ someLooooooooooooooooongFunction();
- bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
- + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
- == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
- && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
- > ccccccccccccccccccccccccccccccccccccccccc;
+ bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ > ccccccccccccccccccccccccccccccccccccccccc;
+ ```
- * ``BOS_All`` (in configuration: ``All``)
+ - `BOS_All` (in configuration: `All`)
Break before operators.
- .. code-block:: c++
+ ```c++
+ LooooooooooongType loooooooooooooooooooooongVariable
+ = someLooooooooooooooooongFunction();
- LooooooooooongType loooooooooooooooooooooongVariable
- = someLooooooooooooooooongFunction();
+ bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+ > ccccccccccccccccccccccccccccccccccccccccc;
+ ```
- bool value = aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
- + aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
- == aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
- && aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
- > ccccccccccccccccccccccccccccccccccccccccc;
+(breakbeforebraces)=
-.. _BreakBeforeBraces:
+**BreakBeforeBraces** (`BraceBreakingStyle`) {versionbadge}`clang-format 3.7` {ref}`¶ <BreakBeforeBraces>`
-**BreakBeforeBraces** (``BraceBreakingStyle``) :versionbadge:`clang-format 3.7` :ref:`¶ <BreakBeforeBraces>`
- The brace breaking style to use.
+: The brace breaking style to use.
Possible values:
- * ``BS_Attach`` (in configuration: ``Attach``)
+ - `BS_Attach` (in configuration: `Attach`)
Always attach braces to surrounding context.
- .. code-block:: c++
-
- namespace N {
- enum E {
- E1,
- E2,
- };
+ ```c++
+ namespace N {
+ enum E {
+ E1,
+ E2,
+ };
- class C {
- public:
- C();
- };
+ class C {
+ public:
+ C();
+ };
- bool baz(int i) {
- try {
- do {
- switch (i) {
- case 1: {
- foobar();
- break;
- }
- default: {
- break;
- }
- }
- } while (--i);
- return true;
- } catch (...) {
- handleError();
- return false;
- }
+ bool baz(int i) {
+ try {
+ do {
+ switch (i) {
+ case 1: {
+ foobar();
+ break;
+ }
+ default: {
+ break;
+ }
+ }
+ } while (--i);
+ return true;
+ } catch (...) {
+ handleError();
+ return false;
}
+ }
- void foo(bool b) {
- if (b) {
- baz(2);
- } else {
- baz(5);
- }
+ void foo(bool b) {
+ if (b) {
+ baz(2);
+ } else {
+ baz(5);
}
+ }
- void bar() { foo(true); }
- } // namespace N
+ void bar() { foo(true); }
+ } // namespace N
+ ```
- * ``BS_Linux`` (in configuration: ``Linux``)
- Like ``Attach``, but break before braces on function, namespace and
+ - `BS_Linux` (in configuration: `Linux`)
+ Like `Attach`, but break before braces on function, namespace and
class definitions.
- .. code-block:: c++
-
- namespace N
- {
- enum E {
- E1,
- E2,
- };
+ ```c++
+ namespace N
+ {
+ enum E {
+ E1,
+ E2,
+ };
- class C
- {
- public:
- C();
- };
+ class C
+ {
+ public:
+ C();
+ };
- bool baz(int i)
- {
- try {
- do {
- switch (i) {
- case 1: {
- foobar();
- break;
- }
- default: {
- break;
- }
- }
- } while (--i);
- return true;
- } catch (...) {
- handleError();
- return false;
- }
+ bool baz(int i)
+ {
+ try {
+ do {
+ switch (i) {
+ case 1: {
+ foobar();
+ break;
+ }
+ default: {
+ break;
+ }
+ }
+ } while (--i);
+ return true;
+ } catch (...) {
+ handleError();
+ return false;
}
+ }
- void foo(bool b)
- {
- if (b) {
- baz(2);
- } else {
- baz(5);
- }
+ void foo(bool b)
+ {
+ if (b) {
+ baz(2);
+ } else {
+ baz(5);
}
+ }
- void bar() { foo(true); }
- } // namespace N
+ void bar() { foo(true); }
+ } // namespace N
+ ```
- * ``BS_Mozilla`` (in configuration: ``Mozilla``)
- Like ``Attach``, but break before braces on enum, function, and record
+ - `BS_Mozilla` (in configuration: `Mozilla`)
+ Like `Attach`, but break before braces on enum, function, and record
definitions.
- .. code-block:: c++
+ ```c++
+ namespace N {
+ enum E
+ {
+ E1,
+ E2,
+ };
- namespace N {
- enum E
- {
- E1,
- E2,
- };
+ class C
+ {
+ public:
+ C();
+ };
- class C
- {
- public:
- C();
- };
+ bool baz(int i)
+ {
+ try {
+ do {
+ switch (i) {
+ case 1: {
+ foobar();
+ break;
+ }
+ default: {
+ break;
+ }
+ }
+ } while (--i);
+ return true;
+ } catch (...) {
+ handleError();
+ return false;
+ }
+ }
- bool baz(int i)
- {
- try {
- do {
- switch (i) {
- case 1: {
- foobar();
- break;
- }
- default: {
- break;
- }
- }
- } while (--i);
- return true;
- } catch (...) {
- handleError();
- return false;
- }
+ void foo(bool b)
+ {
+ if (b) {
+ baz(2);
+ } else {
+ baz(5);
}
+ }
- void foo(bool b)
- {
- if (b) {
- baz(2);
- } else {
- baz(5);
- }
+ void bar() { foo(true); }
+ } // namespace N
+ ```
+
+ - `BS_Stroustrup` (in configuration: `Stroustrup`)
+ Like `Attach`, but break before function definitions, `catch`, and
+ `else`.
+
+ ```c++
+ namespace N {
+ enum E {
+ E1,
+ E2,
+ };
+
+ class C {
+ public:
+ C();
+ };
+
+ bool baz(int i)
+ {
+ try {
+ do {
+ switch (i) {
+ case 1: {
+ foobar();
+ break;
+ }
+ default: {
+ break;
+ }
+ }
+ } while (--i);
+ return true;
+ }
+ catch (...) {
+ handleError();
+ return false;
}
+ }
- void bar() { foo(true); }
- } // namespace N
+ void foo(bool b)
+ {
+ if (b) {
+ baz(2);
+ }
+ else {
+ baz(5);
+ }
+ }
- * ``BS_Stroustrup`` (in configuration: ``Stroustrup``)
- Like ``Attach``, but break before function definitions, ``catch``, and
- ``else``.
+ void bar() { foo(true); }
+ } // namespace N
+ ```
- .. code-block:: c++
+ - `BS_Allman` (in configuration: `Allman`)
+ Always break before braces.
- namespace N {
- enum E {
- E1,
- E2,
- };
+ ```c++
+ namespace N
+ {
+ enum E
+ {
+ E1,
+ E2,
+ };
- class C {
- public:
- C();
- };
+ class C
+ {
+ public:
+ C();
+ };
- bool baz(int i)
+ bool baz(int i)
+ {
+ try
{
- try {
- do {
- switch (i) {
- case 1: {
- foobar();
- break;
- }
- default: {
- break;
- }
- }
- } while (--i);
- return true;
- }
- catch (...) {
- handleError();
- return false;
- }
+ do
+ {
+ switch (i)
+ {
+ case 1:
+ {
+ foobar();
+ break;
+ }
+ default:
+ {
+ break;
+ }
+ }
+ } while (--i);
+ return true;
}
-
- void foo(bool b)
+ catch (...)
{
- if (b) {
- baz(2);
- }
- else {
- baz(5);
- }
+ handleError();
+ return false;
}
+ }
- void bar() { foo(true); }
- } // namespace N
+ void foo(bool b)
+ {
+ if (b)
+ {
+ baz(2);
+ }
+ else
+ {
+ baz(5);
+ }
+ }
- * ``BS_Allman`` (in configuration: ``Allman``)
- Always break before braces.
+ void bar() { foo(true); }
+ } // namespace N
+ ```
- .. code-block:: c++
+ - `BS_Whitesmiths` (in configuration: `Whitesmiths`)
+ Like `Allman` but always indent braces and line up code with braces.
- namespace N
+ ```c++
+ namespace N
{
- enum E
+ enum E
{
- E1,
- E2,
+ E1,
+ E2,
};
- class C
+ class C
{
- public:
- C();
+ public:
+ C();
};
- bool baz(int i)
+ bool baz(int i)
{
- try
+ try
{
- do
+ do
{
- switch (i)
+ switch (i)
{
case 1:
{
- foobar();
- break;
+ foobar();
+ break;
}
default:
{
- break;
+ break;
}
}
} while (--i);
- return true;
+ return true;
}
- catch (...)
+ catch (...)
{
- handleError();
- return false;
+ handleError();
+ return false;
}
}
- void foo(bool b)
+ void foo(bool b)
{
- if (b)
+ if (b)
{
- baz(2);
+ baz(2);
}
- else
+ else
{
- baz(5);
+ baz(5);
}
}
- void bar() { foo(true); }
+ void bar() { foo(true); }
} // namespace N
+ ```
- * ``BS_Whitesmiths`` (in configuration: ``Whitesmiths``)
- Like ``Allman`` but always indent braces and line up code with braces.
-
- .. code-block:: c++
-
- namespace N
- {
- enum E
- {
- E1,
- E2,
- };
-
- class C
- {
- public:
- C();
- };
-
- bool baz(int i)
- {
- try
- {
- do
- {
- switch (i)
- {
- case 1:
- {
- foobar();
- break;
- }
- default:
- {
- break;
- }
- }
- } while (--i);
- return true;
- }
- catch (...)
- {
- handleError();
- return false;
- }
- }
-
- void foo(bool b)
- {
- if (b)
- {
- baz(2);
- }
- else
- {
- baz(5);
- }
- }
-
- void bar() { foo(true); }
- } // namespace N
-
- * ``BS_GNU`` (in configuration: ``GNU``)
+ - `BS_GNU` (in configuration: `GNU`)
Always break before braces and add an extra level of indentation to
braces of control statements, not to those of class, function
or other definitions.
- .. code-block:: c++
-
- namespace N
- {
- enum E
- {
- E1,
- E2,
- };
-
- class C
- {
- public:
- C();
- };
-
- bool baz(int i)
- {
- try
- {
- do
- {
- switch (i)
- {
- case 1:
- {
- foobar();
- break;
- }
- default:
- {
- break;
- }
- }
- }
- while (--i);
- return true;
- }
- catch (...)
- {
- handleError();
- return false;
- }
- }
-
- void foo(bool b)
- {
- if (b)
- {
- baz(2);
- }
- else
- {
- baz(5);
- }
- }
-
- void bar() { foo(true); }
- } // namespace N
-
- * ``BS_WebKit`` (in configuration: ``WebKit``)
- Like ``Attach``, but break before functions.
-
- .. code-block:: c++
-
- namespace N {
- enum E {
- E1,
- E2,
- };
+ ```c++
+ namespace N
+ {
+ enum E
+ {
+ E1,
+ E2,
+ };
- class C {
- public:
- C();
- };
+ class C
+ {
+ public:
+ C();
+ };
- bool baz(int i)
- {
- try {
- do {
- switch (i) {
- case 1: {
- foobar();
- break;
- }
- default: {
- break;
- }
+ bool baz(int i)
+ {
+ try
+ {
+ do
+ {
+ switch (i)
+ {
+ case 1:
+ {
+ foobar();
+ break;
+ }
+ default:
+ {
+ break;
+ }
+ }
}
- } while (--i);
+ while (--i);
return true;
- } catch (...) {
+ }
+ catch (...)
+ {
handleError();
return false;
}
- }
+ }
- void foo(bool b)
- {
- if (b) {
+ void foo(bool b)
+ {
+ if (b)
+ {
baz(2);
- } else {
+ }
+ else
+ {
baz(5);
}
+ }
+
+ void bar() { foo(true); }
+ } // namespace N
+ ```
+
+ - `BS_WebKit` (in configuration: `WebKit`)
+ Like `Attach`, but break before functions.
+
+ ```c++
+ namespace N {
+ enum E {
+ E1,
+ E2,
+ };
+
+ class C {
+ public:
+ C();
+ };
+
+ bool baz(int i)
+ {
+ try {
+ do {
+ switch (i) {
+ case 1: {
+ foobar();
+ break;
+ }
+ default: {
+ break;
+ }
+ }
+ } while (--i);
+ return true;
+ } catch (...) {
+ handleError();
+ return false;
}
+ }
- void bar() { foo(true); }
- } // namespace N
+ void foo(bool b)
+ {
+ if (b) {
+ baz(2);
+ } else {
+ baz(5);
+ }
+ }
+
+ void bar() { foo(true); }
+ } // namespace N
+ ```
- * ``BS_Custom`` (in configuration: ``Custom``)
- Configure each individual brace in ``BraceWrapping``.
+ - `BS_Custom` (in configuration: `Custom`)
+ Configure each individual brace in `BraceWrapping`.
-.. _BreakBeforeCloseBracketBracedList:
+(breakbeforeclosebracketbracedlist)=
-**BreakBeforeCloseBracketBracedList** (``Boolean``) :versionbadge:`clang-format 22` :ref:`¶ <BreakBeforeCloseBracketBracedList>`
- Force break before the right bracket of a braced initializer list (when
- ``Cpp11BracedListStyle`` is ``true``) when the list exceeds the column
+**BreakBeforeCloseBracketBracedList** (`Boolean`) {versionbadge}`clang-format 22` {ref}`¶ <BreakBeforeCloseBracketBracedList>`
+
+: Force break before the right bracket of a braced initializer list (when
+ `Cpp11BracedListStyle` is `true`) when the list exceeds the column
limit. The break before the right bracket is only made if there is a
break after the opening bracket.
- .. code-block:: c++
+ ```c++
+ true: false:
+ vector<int> x { vs. vector<int> x {
+ 1, 2, 3 1, 2, 3}
+ }
+ ```
- true: false:
- vector<int> x { vs. vector<int> x {
- 1, 2, 3 1, 2, 3}
- }
+(breakbeforeclosebracketfunction)=
-.. _BreakBeforeCloseBracketFunction:
+**BreakBeforeCloseBracketFunction** (`Boolean`) {versionbadge}`clang-format 22` {ref}`¶ <BreakBeforeCloseBracketFunction>`
-**BreakBeforeCloseBracketFunction** (``Boolean``) :versionbadge:`clang-format 22` :ref:`¶ <BreakBeforeCloseBracketFunction>`
- Force break before the right parenthesis of a function (declaration,
+: Force break before the right parenthesis of a function (declaration,
definition, call) when the parameters exceed the column limit.
- .. code-block:: c++
+ ```c++
+ true: false:
+ foo ( vs. foo (
+ a , b a , b)
+ )
+ ```
- true: false:
- foo ( vs. foo (
- a , b a , b)
- )
+(breakbeforeclosebracketif)=
-.. _BreakBeforeCloseBracketIf:
+**BreakBeforeCloseBracketIf** (`Boolean`) {versionbadge}`clang-format 22` {ref}`¶ <BreakBeforeCloseBracketIf>`
-**BreakBeforeCloseBracketIf** (``Boolean``) :versionbadge:`clang-format 22` :ref:`¶ <BreakBeforeCloseBracketIf>`
- Force break before the right parenthesis of an if control statement
+: Force break before the right parenthesis of an if control statement
when the expression exceeds the column limit. The break before the
closing parenthesis is only made if there is a break after the opening
parenthesis.
- .. code-block:: c++
+ ```c++
+ true: false:
+ if constexpr ( vs. if constexpr (
+ a || b a || b )
+ )
+ ```
- true: false:
- if constexpr ( vs. if constexpr (
- a || b a || b )
- )
+(breakbeforeclosebracketloop)=
-.. _BreakBeforeCloseBracketLoop:
+**BreakBeforeCloseBracketLoop** (`Boolean`) {versionbadge}`clang-format 22` {ref}`¶ <BreakBeforeCloseBracketLoop>`
-**BreakBeforeCloseBracketLoop** (``Boolean``) :versionbadge:`clang-format 22` :ref:`¶ <BreakBeforeCloseBracketLoop>`
- Force break before the right parenthesis of a loop control statement
+: Force break before the right parenthesis of a loop control statement
when the expression exceeds the column limit. The break before the
closing parenthesis is only made if there is a break after the opening
parenthesis.
- .. code-block:: c++
+ ```c++
+ true: false:
+ while ( vs. while (
+ a && b a && b) {
+ ) {
+ ```
- true: false:
- while ( vs. while (
- a && b a && b) {
- ) {
+(breakbeforeclosebracketswitch)=
-.. _BreakBeforeCloseBracketSwitch:
+**BreakBeforeCloseBracketSwitch** (`Boolean`) {versionbadge}`clang-format 22` {ref}`¶ <BreakBeforeCloseBracketSwitch>`
-**BreakBeforeCloseBracketSwitch** (``Boolean``) :versionbadge:`clang-format 22` :ref:`¶ <BreakBeforeCloseBracketSwitch>`
- Force break before the right parenthesis of a switch control statement
+: Force break before the right parenthesis of a switch control statement
when the expression exceeds the column limit. The break before the
closing parenthesis is only made if there is a break after the opening
parenthesis.
- .. code-block:: c++
+ ```c++
+ true: false:
+ switch ( vs. switch (
+ a + b a + b) {
+ ) {
+ ```
- true: false:
- switch ( vs. switch (
- a + b a + b) {
- ) {
+(breakbeforeconceptdeclarations)=
-.. _BreakBeforeConceptDeclarations:
+**BreakBeforeConceptDeclarations** (`BreakBeforeConceptDeclarationsStyle`) {versionbadge}`clang-format 12` {ref}`¶ <BreakBeforeConceptDeclarations>`
-**BreakBeforeConceptDeclarations** (``BreakBeforeConceptDeclarationsStyle``) :versionbadge:`clang-format 12` :ref:`¶ <BreakBeforeConceptDeclarations>`
- The concept declaration style to use.
+: The concept declaration style to use.
Possible values:
- * ``BBCDS_Never`` (in configuration: ``Never``)
- Keep the template declaration line together with ``concept``.
-
- .. code-block:: c++
+ - `BBCDS_Never` (in configuration: `Never`)
+ Keep the template declaration line together with `concept`.
- template <typename T> concept C = ...;
+ ```c++
+ template <typename T> concept C = ...;
+ ```
- * ``BBCDS_Allowed`` (in configuration: ``Allowed``)
- Breaking between template declaration and ``concept`` is allowed. The
+ - `BBCDS_Allowed` (in configuration: `Allowed`)
+ Breaking between template declaration and `concept` is allowed. The
actual behavior depends on the content and line breaking rules and
penalties.
- * ``BBCDS_Always`` (in configuration: ``Always``)
- Always break before ``concept``, putting it in the line after the
+ - `BBCDS_Always` (in configuration: `Always`)
+ Always break before `concept`, putting it in the line after the
template declaration.
- .. code-block:: c++
+ ```c++
+ template <typename T>
+ concept C = ...;
+ ```
- template <typename T>
- concept C = ...;
+(breakbeforeinlineasmcolon)=
-.. _BreakBeforeInlineASMColon:
+**BreakBeforeInlineASMColon** (`BreakBeforeInlineASMColonStyle`) {versionbadge}`clang-format 16` {ref}`¶ <BreakBeforeInlineASMColon>`
-**BreakBeforeInlineASMColon** (``BreakBeforeInlineASMColonStyle``) :versionbadge:`clang-format 16` :ref:`¶ <BreakBeforeInlineASMColon>`
- The inline ASM colon style to use.
+: The inline ASM colon style to use.
Possible values:
- * ``BBIAS_Never`` (in configuration: ``Never``)
+ - `BBIAS_Never` (in configuration: `Never`)
No break before inline ASM colon.
- .. code-block:: c++
-
- asm volatile("string", : : val);
+ ```c++
+ asm volatile("string", : : val);
+ ```
- * ``BBIAS_OnlyMultiline`` (in configuration: ``OnlyMultiline``)
+ - `BBIAS_OnlyMultiline` (in configuration: `OnlyMultiline`)
Break before inline ASM colon if the line length is longer than column
limit.
- .. code-block:: c++
+ ```c++
+ asm volatile("string", : : val);
+ asm("cmoveq %1, %2, %[result]"
+ : [result] "=r"(result)
+ : "r"(test), "r"(new), "[result]"(old));
+ ```
- asm volatile("string", : : val);
- asm("cmoveq %1, %2, %[result]"
- : [result] "=r"(result)
- : "r"(test), "r"(new), "[result]"(old));
-
- * ``BBIAS_Always`` (in configuration: ``Always``)
+ - `BBIAS_Always` (in configuration: `Always`)
Always break before inline ASM colon.
- .. code-block:: c++
+ ```c++
+ asm volatile("string",
+ :
+ : val);
+ ```
- asm volatile("string",
- :
- : val);
+(breakbeforereturntype)=
-.. _BreakBeforeReturnType:
+**BreakBeforeReturnType** (`BreakBeforeReturnTypeStyle`) {versionbadge}`clang-format 23` {ref}`¶ <BreakBeforeReturnType>`
-**BreakBeforeReturnType** (``BreakBeforeReturnTypeStyle``) :versionbadge:`clang-format 23` :ref:`¶ <BreakBeforeReturnType>`
- The function declaration/definition return type breaking style to use.
- Trailing return types (``auto f() -> T``) are not affected. To have
- identifier macros (e.g. ``__always_inline``) treated as specifiers,
- add them to ``AttributeMacros``.
+: The function declaration/definition return type breaking style to use.
+ Trailing return types (`auto f() -> T`) are not affected. To have
+ identifier macros (e.g. `__always_inline`) treated as specifiers,
+ add them to `AttributeMacros`.
Possible values:
- * ``BBRTS_None`` (in configuration: ``None``)
+ - `BBRTS_None` (in configuration: `None`)
Do not force a break before the return type.
- * ``BBRTS_All`` (in configuration: ``All``)
+ - `BBRTS_All` (in configuration: `All`)
Always break before the return type.
- .. code-block:: c++
-
- static inline
- void f();
+ ```c++
+ static inline
+ void f();
+ ```
- * ``BBRTS_TopLevel`` (in configuration: ``TopLevel``)
+ - `BBRTS_TopLevel` (in configuration: `TopLevel`)
Break before the return type of top-level functions only.
- * ``BBRTS_AllDefinitions`` (in configuration: ``AllDefinitions``)
+ - `BBRTS_AllDefinitions` (in configuration: `AllDefinitions`)
Break before the return type of function definitions only.
- * ``BBRTS_TopLevelDefinitions`` (in configuration: ``TopLevelDefinitions``)
+ - `BBRTS_TopLevelDefinitions` (in configuration: `TopLevelDefinitions`)
Break before the return type of top-level definitions only.
-.. _BreakBeforeTemplateCloser:
+(breakbeforetemplatecloser)=
-**BreakBeforeTemplateCloser** (``Boolean``) :versionbadge:`clang-format 21` :ref:`¶ <BreakBeforeTemplateCloser>`
- If ``true``, break before a template closing bracket (``>``) when there is
- a line break after the matching opening bracket (``<``).
+**BreakBeforeTemplateCloser** (`Boolean`) {versionbadge}`clang-format 21` {ref}`¶ <BreakBeforeTemplateCloser>`
- .. code-block:: c++
+: If `true`, break before a template closing bracket (`>`) when there is
+ a line break after the matching opening bracket (`<`).
- true:
- template <typename Foo, typename Bar>
+ ```c++
+ true:
+ template <typename Foo, typename Bar>
- template <typename Foo,
- typename Bar>
+ template <typename Foo,
+ typename Bar>
- template <
- typename Foo,
- typename Bar
- >
+ template <
+ typename Foo,
+ typename Bar
+ >
- false:
- template <typename Foo, typename Bar>
+ false:
+ template <typename Foo, typename Bar>
- template <typename Foo,
- typename Bar>
+ template <typename Foo,
+ typename Bar>
- template <
- typename Foo,
- typename Bar>
+ template <
+ typename Foo,
+ typename Bar>
+ ```
-.. _BreakBeforeTernaryOperators:
+(breakbeforeternaryoperators)=
-**BreakBeforeTernaryOperators** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <BreakBeforeTernaryOperators>`
- If ``true``, ternary operators will be placed after line breaks.
+**BreakBeforeTernaryOperators** (`Boolean`) {versionbadge}`clang-format 3.7` {ref}`¶ <BreakBeforeTernaryOperators>`
- .. code-block:: c++
+: If `true`, ternary operators will be placed after line breaks.
- true:
- veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription
- ? firstValue
- : SecondValueVeryVeryVeryVeryLong;
+ ```c++
+ true:
+ veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription
+ ? firstValue
+ : SecondValueVeryVeryVeryVeryLong;
- false:
- veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ?
- firstValue :
- SecondValueVeryVeryVeryVeryLong;
+ false:
+ veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ?
+ firstValue :
+ SecondValueVeryVeryVeryVeryLong;
+ ```
-.. _BreakBinaryOperations:
+(breakbinaryoperations)=
-**BreakBinaryOperations** (``BreakBinaryOperationsOptions``) :versionbadge:`clang-format 20` :ref:`¶ <BreakBinaryOperations>`
- The break binary operations style to use.
+**BreakBinaryOperations** (`BreakBinaryOperationsOptions`) {versionbadge}`clang-format 20` {ref}`¶ <BreakBinaryOperations>`
+
+: The break binary operations style to use.
Nested configuration flags:
- Options for ``BreakBinaryOperations``.
+ Options for `BreakBinaryOperations`.
- If specified as a simple string (e.g. ``OnePerLine``), it behaves like
+ If specified as a simple string (e.g. `OnePerLine`), it behaves like
the original enum and applies to all binary operators.
If specified as a struct, allows per-operator configuration:
- .. code-block:: yaml
-
- BreakBinaryOperations:
- Default: Never
- PerOperator:
- - Operators: ['&&', '||']
- Style: OnePerLine
- MinChainLength: 3
+ ```yaml
+ BreakBinaryOperations:
+ Default: Never
+ PerOperator:
+ - Operators: ['&&', '||']
+ Style: OnePerLine
+ MinChainLength: 3
+ ```
- * ``BreakBinaryOperationsStyle Default`` :versionbadge:`clang-format 23`
+ - `BreakBinaryOperationsStyle Default` {versionbadge}`clang-format 23`
- The default break style for operators not covered by ``PerOperator``.
+ The default break style for operators not covered by `PerOperator`.
Possible values:
- * ``BBO_Never`` (in configuration: ``Never``)
+ - `BBO_Never` (in configuration: `Never`)
Don't break binary operations
- .. code-block:: c++
+ ```c++
+ aaa + bbbb * ccccc - ddddd +
+ eeeeeeeeeeeeeeee;
+ ```
- aaa + bbbb * ccccc - ddddd +
- eeeeeeeeeeeeeeee;
-
- * ``BBO_OnePerLine`` (in configuration: ``OnePerLine``)
+ - `BBO_OnePerLine` (in configuration: `OnePerLine`)
Binary operations will either be all on the same line, or each operation
will have one line each.
- .. code-block:: c++
-
- aaa +
- bbbb *
- ccccc -
- ddddd +
- eeeeeeeeeeeeeeee;
+ ```c++
+ aaa +
+ bbbb *
+ ccccc -
+ ddddd +
+ eeeeeeeeeeeeeeee;
+ ```
- * ``BBO_RespectPrecedence`` (in configuration: ``RespectPrecedence``)
+ - `BBO_RespectPrecedence` (in configuration: `RespectPrecedence`)
Binary operations of a particular precedence that exceed the column
limit will have one line each.
- .. code-block:: c++
+ ```c++
+ aaa +
+ bbbb * ccccc -
+ ddddd +
+ eeeeeeeeeeeeeeee;
+ ```
- aaa +
- bbbb * ccccc -
- ddddd +
- eeeeeeeeeeeeeeee;
+ - `List of BinaryOperationBreakRules PerOperator` Per-operator override rules.
- * ``List of BinaryOperationBreakRules PerOperator`` Per-operator override rules.
+ - `List of Strings Operators` {versionbadge}`clang-format 23` The list of operators this rule applies to, e.g. `&&`, `||`, `|`.
+ Alternative spellings (e.g. `and` for `&&`) are accepted.
- * ``List of Strings Operators`` :versionbadge:`clang-format 23` The list of operators this rule applies to, e.g. ``&&``, ``||``, ``|``.
- Alternative spellings (e.g. ``and`` for ``&&``) are accepted.
-
- * ``BreakBinaryOperationsStyle Style``
- The break style for these operators (defaults to ``OnePerLine``).
+ - `BreakBinaryOperationsStyle Style`
+ The break style for these operators (defaults to `OnePerLine`).
Possible values:
- * ``BBO_Never`` (in configuration: ``Never``)
+ - `BBO_Never` (in configuration: `Never`)
Don't break binary operations
- .. code-block:: c++
-
- aaa + bbbb * ccccc - ddddd +
- eeeeeeeeeeeeeeee;
+ ```c++
+ aaa + bbbb * ccccc - ddddd +
+ eeeeeeeeeeeeeeee;
+ ```
- * ``BBO_OnePerLine`` (in configuration: ``OnePerLine``)
+ - `BBO_OnePerLine` (in configuration: `OnePerLine`)
Binary operations will either be all on the same line, or each operation
will have one line each.
- .. code-block:: c++
+ ```c++
+ aaa +
+ bbbb *
+ ccccc -
+ ddddd +
+ eeeeeeeeeeeeeeee;
+ ```
- aaa +
- bbbb *
- ccccc -
- ddddd +
- eeeeeeeeeeeeeeee;
-
- * ``BBO_RespectPrecedence`` (in configuration: ``RespectPrecedence``)
+ - `BBO_RespectPrecedence` (in configuration: `RespectPrecedence`)
Binary operations of a particular precedence that exceed the column
limit will have one line each.
- .. code-block:: c++
+ ```c++
+ aaa +
+ bbbb * ccccc -
+ ddddd +
+ eeeeeeeeeeeeeeee;
+ ```
- aaa +
- bbbb * ccccc -
- ddddd +
- eeeeeeeeeeeeeeee;
+ - `unsigned MinChainLength` Minimum number of operands in a chain before the rule triggers.
+ For example, `a && b && c` is a chain of length 3.
+ `0` means always break (when the line is too long).
- * ``unsigned MinChainLength`` Minimum number of operands in a chain before the rule triggers.
- For example, ``a && b && c`` is a chain of length 3.
- ``0`` means always break (when the line is too long).
+(breakconstructorinitializers)=
-.. _BreakConstructorInitializers:
+**BreakConstructorInitializers** (`BreakConstructorInitializersStyle`) {versionbadge}`clang-format 5` {ref}`¶ <BreakConstructorInitializers>`
-**BreakConstructorInitializers** (``BreakConstructorInitializersStyle``) :versionbadge:`clang-format 5` :ref:`¶ <BreakConstructorInitializers>`
- The break constructor initializers style to use.
+: The break constructor initializers style to use.
Possible values:
- * ``BCIS_BeforeColon`` (in configuration: ``BeforeColon``)
+ - `BCIS_BeforeColon` (in configuration: `BeforeColon`)
Break constructor initializers before the colon and after the commas.
- .. code-block:: c++
-
- Constructor()
- : initializer1(),
- initializer2()
+ ```c++
+ Constructor()
+ : initializer1(),
+ initializer2()
+ ```
- * ``BCIS_BeforeComma`` (in configuration: ``BeforeComma``)
+ - `BCIS_BeforeComma` (in configuration: `BeforeComma`)
Break constructor initializers before the colon and commas, and align
the commas with the colon.
- .. code-block:: c++
+ ```c++
+ Constructor()
+ : initializer1()
+ , initializer2()
+ ```
- Constructor()
- : initializer1()
- , initializer2()
-
- * ``BCIS_AfterColon`` (in configuration: ``AfterColon``)
+ - `BCIS_AfterColon` (in configuration: `AfterColon`)
Break constructor initializers after the colon and commas.
- .. code-block:: c++
-
- Constructor() :
- initializer1(),
- initializer2()
+ ```c++
+ Constructor() :
+ initializer1(),
+ initializer2()
+ ```
- * ``BCIS_AfterComma`` (in configuration: ``AfterComma``)
+ - `BCIS_AfterComma` (in configuration: `AfterComma`)
Break constructor initializers only after the commas.
- .. code-block:: c++
+ ```c++
+ Constructor() : initializer1(),
+ initializer2()
+ ```
- Constructor() : initializer1(),
- initializer2()
+(breakfunctiondeclarationparameters)=
-.. _BreakFunctionDeclarationParameters:
+**BreakFunctionDeclarationParameters** (`Boolean`) {versionbadge}`clang-format 23` {ref}`¶ <BreakFunctionDeclarationParameters>`
-**BreakFunctionDeclarationParameters** (``Boolean``) :versionbadge:`clang-format 23` :ref:`¶ <BreakFunctionDeclarationParameters>`
- If ``true``, clang-format will always break before function declaration
+: If `true`, clang-format will always break before function declaration
parameters.
- .. code-block:: c++
+ ```c++
+ true:
+ void functionDeclaration(
+ int A, int B);
- true:
- void functionDeclaration(
- int A, int B);
+ false:
+ void functionDeclaration(int A, int B);
- false:
- void functionDeclaration(int A, int B);
+ ```
+
+(breakfunctiondefinitionparameters)=
-.. _BreakFunctionDefinitionParameters:
+**BreakFunctionDefinitionParameters** (`Boolean`) {versionbadge}`clang-format 19` {ref}`¶ <BreakFunctionDefinitionParameters>`
-**BreakFunctionDefinitionParameters** (``Boolean``) :versionbadge:`clang-format 19` :ref:`¶ <BreakFunctionDefinitionParameters>`
- If ``true``, clang-format will always break before function definition
+: If `true`, clang-format will always break before function definition
parameters.
- .. code-block:: c++
+ ```c++
+ true:
+ void functionDefinition(
+ int A, int B) {}
- true:
- void functionDefinition(
- int A, int B) {}
+ false:
+ void functionDefinition(int A, int B) {}
- false:
- void functionDefinition(int A, int B) {}
+ ```
+
+(breakinheritancelist)=
-.. _BreakInheritanceList:
+**BreakInheritanceList** (`BreakInheritanceListStyle`) {versionbadge}`clang-format 7` {ref}`¶ <BreakInheritanceList>`
-**BreakInheritanceList** (``BreakInheritanceListStyle``) :versionbadge:`clang-format 7` :ref:`¶ <BreakInheritanceList>`
- The inheritance list style to use.
+: The inheritance list style to use.
Possible values:
- * ``BILS_BeforeColon`` (in configuration: ``BeforeColon``)
+ - `BILS_BeforeColon` (in configuration: `BeforeColon`)
Break inheritance list before the colon and after the commas.
- .. code-block:: c++
+ ```c++
+ class Foo
+ : Base1,
+ Base2
+ {};
+ ```
- class Foo
- : Base1,
- Base2
- {};
-
- * ``BILS_BeforeComma`` (in configuration: ``BeforeComma``)
+ - `BILS_BeforeComma` (in configuration: `BeforeComma`)
Break inheritance list before the colon and commas, and align
the commas with the colon.
- .. code-block:: c++
-
- class Foo
- : Base1
- , Base2
- {};
+ ```c++
+ class Foo
+ : Base1
+ , Base2
+ {};
+ ```
- * ``BILS_AfterColon`` (in configuration: ``AfterColon``)
+ - `BILS_AfterColon` (in configuration: `AfterColon`)
Break inheritance list after the colon and commas.
- .. code-block:: c++
+ ```c++
+ class Foo :
+ Base1,
+ Base2
+ {};
+ ```
- class Foo :
- Base1,
- Base2
- {};
-
- * ``BILS_AfterComma`` (in configuration: ``AfterComma``)
+ - `BILS_AfterComma` (in configuration: `AfterComma`)
Break inheritance list only after the commas.
- .. code-block:: c++
+ ```c++
+ class Foo : Base1,
+ Base2
+ {};
+ ```
- class Foo : Base1,
- Base2
- {};
+(breakstringliterals)=
-.. _BreakStringLiterals:
+**BreakStringLiterals** (`Boolean`) {versionbadge}`clang-format 3.9` {ref}`¶ <BreakStringLiterals>`
-**BreakStringLiterals** (``Boolean``) :versionbadge:`clang-format 3.9` :ref:`¶ <BreakStringLiterals>`
- Allow breaking string literals when formatting.
+: Allow breaking string literals when formatting.
In C, C++, and Objective-C:
- .. code-block:: c++
-
- true:
- const char* x = "veryVeryVeryVeryVeryVe"
- "ryVeryVeryVeryVeryVery"
- "VeryLongString";
+ ```c++
+ true:
+ const char* x = "veryVeryVeryVeryVeryVe"
+ "ryVeryVeryVeryVeryVery"
+ "VeryLongString";
- false:
- const char* x =
- "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString";
+ false:
+ const char* x =
+ "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString";
+ ```
In C# and Java:
- .. code-block:: c++
-
- true:
- string x = "veryVeryVeryVeryVeryVe" +
- "ryVeryVeryVeryVeryVery" +
- "VeryLongString";
+ ```c++
+ true:
+ string x = "veryVeryVeryVeryVeryVe" +
+ "ryVeryVeryVeryVeryVery" +
+ "VeryLongString";
- false:
- string x =
- "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString";
+ false:
+ string x =
+ "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString";
+ ```
C# interpolated strings are not broken.
In Verilog:
- .. code-block:: c++
+ ```c++
+ true:
+ string x = {"veryVeryVeryVeryVeryVe",
+ "ryVeryVeryVeryVeryVery",
+ "VeryLongString"};
- true:
- string x = {"veryVeryVeryVeryVeryVe",
- "ryVeryVeryVeryVeryVery",
- "VeryLongString"};
+ false:
+ string x =
+ "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString";
+ ```
- false:
- string x =
- "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString";
+(breaktemplatedeclarations)=
-.. _BreakTemplateDeclarations:
+**BreakTemplateDeclarations** (`BreakTemplateDeclarationsStyle`) {versionbadge}`clang-format 19` {ref}`¶ <BreakTemplateDeclarations>`
-**BreakTemplateDeclarations** (``BreakTemplateDeclarationsStyle``) :versionbadge:`clang-format 19` :ref:`¶ <BreakTemplateDeclarations>`
- The template declaration breaking style to use.
+: The template declaration breaking style to use.
Possible values:
- * ``BTDS_Leave`` (in configuration: ``Leave``)
+ - `BTDS_Leave` (in configuration: `Leave`)
Do not change the line breaking before the declaration.
- .. code-block:: c++
-
- template <typename T>
- T foo() {
- }
- template <typename T> T foo(int aaaaaaaaaaaaaaaaaaaaa,
- int bbbbbbbbbbbbbbbbbbbbb) {
- }
+ ```c++
+ template <typename T>
+ T foo() {
+ }
+ template <typename T> T foo(int aaaaaaaaaaaaaaaaaaaaa,
+ int bbbbbbbbbbbbbbbbbbbbb) {
+ }
+ ```
- * ``BTDS_No`` (in configuration: ``No``)
+ - `BTDS_No` (in configuration: `No`)
Do not force break before declaration.
- ``PenaltyBreakTemplateDeclaration`` is taken into account.
+ `PenaltyBreakTemplateDeclaration` is taken into account.
- .. code-block:: c++
-
- template <typename T> T foo() {
- }
- template <typename T> T foo(int aaaaaaaaaaaaaaaaaaaaa,
- int bbbbbbbbbbbbbbbbbbbbb) {
- }
+ ```c++
+ template <typename T> T foo() {
+ }
+ template <typename T> T foo(int aaaaaaaaaaaaaaaaaaaaa,
+ int bbbbbbbbbbbbbbbbbbbbb) {
+ }
+ ```
- * ``BTDS_MultiLine`` (in configuration: ``MultiLine``)
+ - `BTDS_MultiLine` (in configuration: `MultiLine`)
Force break after template declaration only when the following
declaration spans multiple lines.
- .. code-block:: c++
-
- template <typename T> T foo() {
- }
- template <typename T>
- T foo(int aaaaaaaaaaaaaaaaaaaaa,
- int bbbbbbbbbbbbbbbbbbbbb) {
- }
+ ```c++
+ template <typename T> T foo() {
+ }
+ template <typename T>
+ T foo(int aaaaaaaaaaaaaaaaaaaaa,
+ int bbbbbbbbbbbbbbbbbbbbb) {
+ }
+ ```
- * ``BTDS_Yes`` (in configuration: ``Yes``)
+ - `BTDS_Yes` (in configuration: `Yes`)
Always break after template declaration.
- .. code-block:: c++
+ ```c++
+ template <typename T>
+ T foo() {
+ }
+ template <typename T>
+ T foo(int aaaaaaaaaaaaaaaaaaaaa,
+ int bbbbbbbbbbbbbbbbbbbbb) {
+ }
+ ```
- template <typename T>
- T foo() {
- }
- template <typename T>
- T foo(int aaaaaaaaaaaaaaaaaaaaa,
- int bbbbbbbbbbbbbbbbbbbbb) {
- }
+(columnlimit)=
-.. _ColumnLimit:
+**ColumnLimit** (`Unsigned`) {versionbadge}`clang-format 3.7` {ref}`¶ <ColumnLimit>`
-**ColumnLimit** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <ColumnLimit>`
- The column limit.
+: The column limit.
- A column limit of ``0`` means that there is no column limit. In this case,
+ 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 unless they contradict other rules.
-.. _CommentPragmas:
+(commentpragmas)=
-**CommentPragmas** (``String``) :versionbadge:`clang-format 3.7` :ref:`¶ <CommentPragmas>`
- A regular expression that describes comments with special meaning,
- which should not be split into lines or otherwise changed.
+**CommentPragmas** (`String`) {versionbadge}`clang-format 3.7` {ref}`¶ <CommentPragmas>`
- .. code-block:: c++
+: A regular expression that describes comments with special meaning,
+ which should not be split into lines or otherwise changed.
- // CommentPragmas: '^ FOOBAR pragma:'
- // Will leave the following line unaffected
- #include <vector> // FOOBAR pragma: keep
+ ```c++
+ // CommentPragmas: '^ FOOBAR pragma:'
+ // Will leave the following line unaffected
+ #include <vector> // FOOBAR pragma: keep
+ ```
-.. _CompactNamespaces:
+(compactnamespaces)=
-**CompactNamespaces** (``Boolean``) :versionbadge:`clang-format 5` :ref:`¶ <CompactNamespaces>`
- If ``true``, consecutive namespace declarations will be on the same
- line. If ``false``, each namespace is declared on a new line.
+**CompactNamespaces** (`Boolean`) {versionbadge}`clang-format 5` {ref}`¶ <CompactNamespaces>`
- .. code-block:: c++
+: If `true`, consecutive namespace declarations will be on the same
+ line. If `false`, each namespace is declared on a new line.
- true:
- namespace Foo { namespace Bar {
- }}
+ ```c++
+ true:
+ namespace Foo { namespace Bar {
+ }}
- false:
- namespace Foo {
- namespace Bar {
- }
- }
+ false:
+ namespace Foo {
+ namespace Bar {
+ }
+ }
+ ```
If it does not fit on a single line, the overflowing namespaces get
wrapped:
- .. code-block:: c++
+ ```c++
+ namespace Foo { namespace Bar {
+ namespace Extra {
+ }}}
+ ```
+
+(constructorinitializerallononelineoroneperline)=
- namespace Foo { namespace Bar {
- namespace Extra {
- }}}
+**ConstructorInitializerAllOnOneLineOrOnePerLine** (`Boolean`) {versionbadge}`clang-format 3.7` {ref}`¶ <ConstructorInitializerAllOnOneLineOrOnePerLine>`
-.. _ConstructorInitializerAllOnOneLineOrOnePerLine:
+: This option is **deprecated**. See `CurrentLine` of
+ `PackConstructorInitializers`.
-**ConstructorInitializerAllOnOneLineOrOnePerLine** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <ConstructorInitializerAllOnOneLineOrOnePerLine>`
- This option is **deprecated**. See ``CurrentLine`` of
- ``PackConstructorInitializers``.
+(constructorinitializerindentwidth)=
-.. _ConstructorInitializerIndentWidth:
+**ConstructorInitializerIndentWidth** (`Unsigned`) {versionbadge}`clang-format 3.7` {ref}`¶ <ConstructorInitializerIndentWidth>`
-**ConstructorInitializerIndentWidth** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <ConstructorInitializerIndentWidth>`
- The number of characters to use for indentation of constructor
+: The number of characters to use for indentation of constructor
initializer lists as well as inheritance lists.
-.. _ContinuationIndentWidth:
+(continuationindentwidth)=
-**ContinuationIndentWidth** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <ContinuationIndentWidth>`
- Indent width for line continuations.
+**ContinuationIndentWidth** (`Unsigned`) {versionbadge}`clang-format 3.7` {ref}`¶ <ContinuationIndentWidth>`
- .. code-block:: c++
+: Indent width for line continuations.
- ContinuationIndentWidth: 2
+ ```c++
+ ContinuationIndentWidth: 2
- int i = // VeryVeryVeryVeryVeryLongComment
- longFunction( // Again a long comment
- arg);
+ int i = // VeryVeryVeryVeryVeryLongComment
+ longFunction( // Again a long comment
+ arg);
+ ```
-.. _Cpp11BracedListStyle:
+(cpp11bracedliststyle)=
-**Cpp11BracedListStyle** (``BracedListStyle``) :versionbadge:`clang-format 3.4` :ref:`¶ <Cpp11BracedListStyle>`
- The style to handle braced lists.
+**Cpp11BracedListStyle** (`BracedListStyle`) {versionbadge}`clang-format 3.4` {ref}`¶ <Cpp11BracedListStyle>`
+
+: The style to handle braced lists.
Possible values:
- * ``BLS_Block`` (in configuration: ``Block``)
+ - `BLS_Block` (in configuration: `Block`)
Best suited for pre C++11 braced lists.
- * Spaces inside the braced list.
- * Line break before the closing brace.
- * Indentation with the block indent.
-
-
- .. code-block:: c++
-
- vector<int> x{ 1, 2, 3, 4 };
- vector<T> x{ {}, {}, {}, {} };
- f(MyMap[{ composite, key }]);
- new int[3]{ 1, 2, 3 };
- Type name{ // Comment
- value
- };
+ - Spaces inside the braced list.
+ - Line break before the closing brace.
+ - Indentation with the block indent.
+
+ ```c++
+ vector<int> x{ 1, 2, 3, 4 };
+ vector<T> x{ {}, {}, {}, {} };
+ f(MyMap[{ composite, key }]);
+ new int[3]{ 1, 2, 3 };
+ Type name{ // Comment
+ value
+ };
+ ```
- * ``BLS_FunctionCall`` (in configuration: ``FunctionCall``)
+ - `BLS_FunctionCall` (in configuration: `FunctionCall`)
Best suited for C++11 braced lists.
- * No spaces inside the braced list.
- * No line break before the closing brace.
- * Indentation with the continuation indent.
+ - No spaces inside the braced list.
+ - No line break before the closing brace.
+ - Indentation with the continuation 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
+ `{}` were the parentheses of a function call with that name. If there
is no name, a zero-length name is assumed.
- .. code-block:: c++
-
- vector<int> x{1, 2, 3, 4};
- vector<T> x{{}, {}, {}, {}};
- f(MyMap[{composite, key}]);
- new int[3]{1, 2, 3};
- Type name{ // Comment
- value};
-
- * ``BLS_AlignFirstComment`` (in configuration: ``AlignFirstComment``)
- Same as ``FunctionCall``, except for the handling of a comment at the
+ ```c++
+ vector<int> x{1, 2, 3, 4};
+ vector<T> x{{}, {}, {}, {}};
+ f(MyMap[{composite, key}]);
+ new int[3]{1, 2, 3};
+ Type name{ // Comment
+ value};
+ ```
+
+ - `BLS_AlignFirstComment` (in configuration: `AlignFirstComment`)
+ Same as `FunctionCall`, except for the handling of a comment at the
begin, it then aligns everything following with the comment.
- * No spaces inside the braced list. (Even for a comment at the first
+ - No spaces inside the braced list. (Even for a comment at the first
position.)
- * No line break before the closing brace.
- * Indentation with the continuation indent, except when followed by a
+ - No line break before the closing brace.
+ - Indentation with the continuation indent, except when followed by a
line comment, then it uses the block indent.
+ ```c++
+ vector<int> x{1, 2, 3, 4};
+ vector<T> x{{}, {}, {}, {}};
+ f(MyMap[{composite, key}]);
+ new int[3]{1, 2, 3};
+ Type name{// Comment
+ value};
+ ```
- .. code-block:: c++
- vector<int> x{1, 2, 3, 4};
- vector<T> x{{}, {}, {}, {}};
- f(MyMap[{composite, key}]);
- new int[3]{1, 2, 3};
- Type name{// Comment
- value};
+(derivelineending)=
+**DeriveLineEnding** (`Boolean`) {versionbadge}`clang-format 10` {ref}`¶ <DeriveLineEnding>`
-.. _DeriveLineEnding:
+: This option is **deprecated**. See `DeriveLF` and `DeriveCRLF` of
+ `LineEnding`.
-**DeriveLineEnding** (``Boolean``) :versionbadge:`clang-format 10` :ref:`¶ <DeriveLineEnding>`
- This option is **deprecated**. See ``DeriveLF`` and ``DeriveCRLF`` of
- ``LineEnding``.
+(derivepointeralignment)=
-.. _DerivePointerAlignment:
+**DerivePointerAlignment** (`Boolean`) {versionbadge}`clang-format 3.7` {ref}`¶ <DerivePointerAlignment>`
-**DerivePointerAlignment** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <DerivePointerAlignment>`
- If ``true``, analyze the formatted file for the most common
- alignment of ``&`` and ``*``.
+: If `true`, analyze the formatted file for the most common
+ alignment of `&` and `*`.
Pointer and reference alignment styles are going to be updated according
to the preferences found in the file.
- ``PointerAlignment`` is then used only as fallback.
+ `PointerAlignment` is then used only as fallback.
+
+(disableformat)=
-.. _DisableFormat:
+**DisableFormat** (`Boolean`) {versionbadge}`clang-format 3.7` {ref}`¶ <DisableFormat>`
-**DisableFormat** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <DisableFormat>`
- Disables formatting completely.
+: Disables formatting completely.
-.. _EmptyLineAfterAccessModifier:
+(emptylineafteraccessmodifier)=
-**EmptyLineAfterAccessModifier** (``EmptyLineAfterAccessModifierStyle``) :versionbadge:`clang-format 13` :ref:`¶ <EmptyLineAfterAccessModifier>`
- Defines when to put an empty line after access modifiers.
- ``EmptyLineBeforeAccessModifier`` configuration handles the number of
+**EmptyLineAfterAccessModifier** (`EmptyLineAfterAccessModifierStyle`) {versionbadge}`clang-format 13` {ref}`¶ <EmptyLineAfterAccessModifier>`
+
+: Defines when to put an empty line after access modifiers.
+ `EmptyLineBeforeAccessModifier` configuration handles the number of
empty lines between two access modifiers.
Possible values:
- * ``ELAAMS_Never`` (in configuration: ``Never``)
+ - `ELAAMS_Never` (in configuration: `Never`)
Remove all empty lines after access modifiers.
- .. code-block:: c++
-
- struct foo {
- private:
- int i;
- protected:
- int j;
- /* comment */
- public:
- foo() {}
- private:
- protected:
- };
+ ```c++
+ struct foo {
+ private:
+ int i;
+ protected:
+ int j;
+ /* comment */
+ public:
+ foo() {}
+ private:
+ protected:
+ };
+ ```
- * ``ELAAMS_Leave`` (in configuration: ``Leave``)
+ - `ELAAMS_Leave` (in configuration: `Leave`)
Keep existing empty lines after access modifiers.
MaxEmptyLinesToKeep is applied instead.
- * ``ELAAMS_Always`` (in configuration: ``Always``)
+ - `ELAAMS_Always` (in configuration: `Always`)
Always add empty line after access modifiers if there are none.
MaxEmptyLinesToKeep is applied also.
- .. code-block:: c++
+ ```c++
+ struct foo {
+ private:
- struct foo {
- private:
+ int i;
+ protected:
- int i;
- protected:
+ int j;
+ /* comment */
+ public:
- int j;
- /* comment */
- public:
+ foo() {}
+ private:
- foo() {}
- private:
+ protected:
- protected:
+ };
+ ```
- };
+(emptylinebeforeaccessmodifier)=
-.. _EmptyLineBeforeAccessModifier:
+**EmptyLineBeforeAccessModifier** (`EmptyLineBeforeAccessModifierStyle`) {versionbadge}`clang-format 12` {ref}`¶ <EmptyLineBeforeAccessModifier>`
-**EmptyLineBeforeAccessModifier** (``EmptyLineBeforeAccessModifierStyle``) :versionbadge:`clang-format 12` :ref:`¶ <EmptyLineBeforeAccessModifier>`
- Defines in which cases to put empty line before access modifiers.
+: Defines in which cases to put empty line before access modifiers.
Possible values:
- * ``ELBAMS_Never`` (in configuration: ``Never``)
+ - `ELBAMS_Never` (in configuration: `Never`)
Remove all empty lines before access modifiers.
- .. code-block:: c++
-
- struct foo {
- private:
- int i;
- protected:
- int j;
- /* comment */
- public:
- foo() {}
- private:
- protected:
- };
+ ```c++
+ struct foo {
+ private:
+ int i;
+ protected:
+ int j;
+ /* comment */
+ public:
+ foo() {}
+ private:
+ protected:
+ };
+ ```
- * ``ELBAMS_Leave`` (in configuration: ``Leave``)
+ - `ELBAMS_Leave` (in configuration: `Leave`)
Keep existing empty lines before access modifiers.
- * ``ELBAMS_LogicalBlock`` (in configuration: ``LogicalBlock``)
+ - `ELBAMS_LogicalBlock` (in configuration: `LogicalBlock`)
Add empty line only when access modifier starts a new logical block.
Logical block is a group of one or more member fields or functions.
- .. code-block:: c++
-
- struct foo {
- private:
- int i;
+ ```c++
+ struct foo {
+ private:
+ int i;
- protected:
- int j;
- /* comment */
- public:
- foo() {}
+ protected:
+ int j;
+ /* comment */
+ public:
+ foo() {}
- private:
- protected:
- };
+ private:
+ protected:
+ };
+ ```
- * ``ELBAMS_Always`` (in configuration: ``Always``)
+ - `ELBAMS_Always` (in configuration: `Always`)
Always add empty line before access modifiers unless access modifier
is at the start of struct or class definition.
- .. code-block:: c++
+ ```c++
+ struct foo {
+ private:
+ int i;
- struct foo {
- private:
- int i;
+ protected:
+ int j;
+ /* comment */
- protected:
- int j;
- /* comment */
+ public:
+ foo() {}
- public:
- foo() {}
+ private:
- private:
+ protected:
+ };
+ ```
- protected:
- };
+(enumtrailingcomma)=
-.. _EnumTrailingComma:
+**EnumTrailingComma** (`EnumTrailingCommaStyle`) {versionbadge}`clang-format 21` {ref}`¶ <EnumTrailingComma>`
-**EnumTrailingComma** (``EnumTrailingCommaStyle``) :versionbadge:`clang-format 21` :ref:`¶ <EnumTrailingComma>`
- Insert a comma (if missing) or remove the comma at the end of an ``enum``
+: Insert a comma (if missing) or remove the comma at the end of an `enum`
enumerator list.
- .. warning::
-
- Setting this option to any value other than ``Leave`` could lead to
- incorrect code formatting due to clang-format's lack of complete semantic
- information. As such, extra care should be taken to review code changes
- made by this option.
+ :::{warning}
+ Setting this option to any value other than `Leave` could lead to
+ incorrect code formatting due to clang-format's lack of complete semantic
+ information. As such, extra care should be taken to review code changes
+ made by this option.
+ :::
Possible values:
- * ``ETC_Leave`` (in configuration: ``Leave``)
+ - `ETC_Leave` (in configuration: `Leave`)
Don't insert or remove trailing commas.
- .. code-block:: c++
-
- enum { a, b, c, };
- enum Color { red, green, blue };
+ ```c++
+ enum { a, b, c, };
+ enum Color { red, green, blue };
+ ```
- * ``ETC_Insert`` (in configuration: ``Insert``)
+ - `ETC_Insert` (in configuration: `Insert`)
Insert trailing commas.
- .. code-block:: c++
+ ```c++
+ enum { a, b, c, };
+ enum Color { red, green, blue, };
+ ```
- enum { a, b, c, };
- enum Color { red, green, blue, };
-
- * ``ETC_Remove`` (in configuration: ``Remove``)
+ - `ETC_Remove` (in configuration: `Remove`)
Remove trailing commas.
- .. code-block:: c++
+ ```c++
+ enum { a, b, c };
+ enum Color { red, green, blue };
+ ```
- enum { a, b, c };
- enum Color { red, green, blue };
+(experimentalautodetectbinpacking)=
-.. _ExperimentalAutoDetectBinPacking:
+**ExperimentalAutoDetectBinPacking** (`Boolean`) {versionbadge}`clang-format 3.7` {ref}`¶ <ExperimentalAutoDetectBinPacking>`
-**ExperimentalAutoDetectBinPacking** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <ExperimentalAutoDetectBinPacking>`
- If ``true``, clang-format detects whether function calls and
+: 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
@@ -4449,589 +4510,608 @@ the configuration (without a prefix: ``Auto``).
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.
+ :::
- .. 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.
+(fixnamespacecomments)=
-.. _FixNamespaceComments:
+**FixNamespaceComments** (`Boolean`) {versionbadge}`clang-format 5` {ref}`¶ <FixNamespaceComments>`
-**FixNamespaceComments** (``Boolean``) :versionbadge:`clang-format 5` :ref:`¶ <FixNamespaceComments>`
- If ``true``, clang-format adds missing namespace end comments for
+: If `true`, clang-format adds missing namespace end comments for
namespaces and fixes invalid existing ones. This doesn't affect short
- namespaces, which are controlled by ``ShortNamespaceLines``.
+ namespaces, which are controlled by `ShortNamespaceLines`.
- .. code-block:: c++
+ ```c++
+ true: false:
+ namespace longNamespace { vs. namespace longNamespace {
+ void foo(); void foo();
+ void bar(); void bar();
+ } // namespace a }
+ namespace shortNamespace { namespace shortNamespace {
+ void baz(); void baz();
+ } }
+ ```
- true: false:
- namespace longNamespace { vs. namespace longNamespace {
- void foo(); void foo();
- void bar(); void bar();
- } // namespace a }
- namespace shortNamespace { namespace shortNamespace {
- void baz(); void baz();
- } }
+(foreachmacros)=
-.. _ForEachMacros:
+**ForEachMacros** (`List of Strings`) {versionbadge}`clang-format 3.7` {ref}`¶ <ForEachMacros>`
-**ForEachMacros** (``List of Strings``) :versionbadge:`clang-format 3.7` :ref:`¶ <ForEachMacros>`
- A vector of macros that should be interpreted as foreach loops
+: A vector of macros that should be interpreted as foreach loops
instead of as function calls.
These are expected to be macros of the form:
- .. code-block:: c++
-
- FOREACH(<variable-declaration>, ...)
- <loop-body>
+ ```c++
+ FOREACH(<variable-declaration>, ...)
+ <loop-body>
+ ```
In the .clang-format configuration file, this can be configured like:
- .. code-block:: yaml
-
- ForEachMacros: [RANGES_FOR, FOREACH]
+ ```yaml
+ ForEachMacros: [RANGES_FOR, FOREACH]
+ ```
For example: BOOST_FOREACH.
-.. _IfMacros:
+(ifmacros)=
-**IfMacros** (``List of Strings``) :versionbadge:`clang-format 13` :ref:`¶ <IfMacros>`
- A vector of macros that should be interpreted as conditionals
+**IfMacros** (`List of Strings`) {versionbadge}`clang-format 13` {ref}`¶ <IfMacros>`
+
+: A vector of macros that should be interpreted as conditionals
instead of as function calls.
These are expected to be macros of the form:
- .. code-block:: c++
-
- IF(...)
- <conditional-body>
- else IF(...)
- <conditional-body>
+ ```c++
+ IF(...)
+ <conditional-body>
+ else IF(...)
+ <conditional-body>
+ ```
In the .clang-format configuration file, this can be configured like:
- .. code-block:: yaml
+ ```yaml
+ IfMacros: [IF]
+ ```
- IfMacros: [IF]
+ For example:
+ [KJ_IF_MAYBE](https://github.com/capnproto/capnproto/blob/master/kjdoc/tour.md#maybes)
- For example: `KJ_IF_MAYBE
- <https://github.com/capnproto/capnproto/blob/master/kjdoc/tour.md#maybes>`_
+(includeblocks)=
-.. _IncludeBlocks:
+**IncludeBlocks** (`IncludeBlocksStyle`) {versionbadge}`clang-format 6` {ref}`¶ <IncludeBlocks>`
-**IncludeBlocks** (``IncludeBlocksStyle``) :versionbadge:`clang-format 6` :ref:`¶ <IncludeBlocks>`
- Dependent on the value, multiple ``#include`` blocks can be sorted
+: Dependent on the value, multiple `#include` blocks can be sorted
as one and divided based on category.
Possible values:
- * ``IBS_Preserve`` (in configuration: ``Preserve``)
- Sort each ``#include`` block separately.
-
- .. code-block:: c++
+ - `IBS_Preserve` (in configuration: `Preserve`)
+ Sort each `#include` block separately.
- #include "b.h" into #include "b.h"
+ ```c++
+ #include "b.h" into #include "b.h"
- #include <lib/main.h> #include "a.h"
- #include "a.h" #include <lib/main.h>
+ #include <lib/main.h> #include "a.h"
+ #include "a.h" #include <lib/main.h>
+ ```
- * ``IBS_Merge`` (in configuration: ``Merge``)
- Merge multiple ``#include`` blocks together and sort as one.
+ - `IBS_Merge` (in configuration: `Merge`)
+ Merge multiple `#include` blocks together and sort as one.
- .. code-block:: c++
+ ```c++
+ #include "b.h" into #include "a.h"
+ #include "b.h"
+ #include <lib/main.h> #include <lib/main.h>
+ #include "a.h"
+ ```
- #include "b.h" into #include "a.h"
- #include "b.h"
- #include <lib/main.h> #include <lib/main.h>
- #include "a.h"
-
- * ``IBS_Regroup`` (in configuration: ``Regroup``)
- Merge multiple ``#include`` blocks together and sort as one.
+ - `IBS_Regroup` (in configuration: `Regroup`)
+ Merge multiple `#include` blocks together and sort as one.
Then split into groups based on category priority. See
- ``IncludeCategories``.
+ `IncludeCategories`.
- .. code-block:: c++
+ ```c++
+ #include "b.h" into #include "a.h"
+ #include "b.h"
+ #include <lib/main.h>
+ #include "a.h" #include <lib/main.h>
+ ```
- #include "b.h" into #include "a.h"
- #include "b.h"
- #include <lib/main.h>
- #include "a.h" #include <lib/main.h>
+(includecategories)=
-.. _IncludeCategories:
+**IncludeCategories** (`List of IncludeCategories`) {versionbadge}`clang-format 3.8` {ref}`¶ <IncludeCategories>`
-**IncludeCategories** (``List of IncludeCategories``) :versionbadge:`clang-format 3.8` :ref:`¶ <IncludeCategories>`
- Regular expressions denoting the
diff erent ``#include`` categories
- used for ordering ``#includes``.
+: Regular expressions denoting the
diff erent `#include` categories
+ used for ordering `#includes`.
- `POSIX extended
- <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html>`_
+ [POSIX
+ extended](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html)
regular expressions are supported.
These regular expressions are matched against the filename of an include
(including the <> or "") in order. The value belonging to the first
- matching regular expression is assigned and ``#includes`` are sorted first
+ matching regular expression is assigned and `#includes` are sorted first
according to increasing category number and then alphabetically within
each category.
If none of the regular expressions match, INT_MAX is assigned as
category. The main header for a source file automatically gets category 0.
- so that it is generally kept at the beginning of the ``#includes``
- (https://llvm.org/docs/CodingStandards.html#include-style). However, you
- can also assign negative priorities if you have certain headers that
- always need to be first.
-
- There is a third and optional field ``SortPriority`` which can used while
- ``IncludeBlocks = IBS_Regroup`` to define the priority in which
- ``#includes`` should be ordered. The value of ``Priority`` defines the
- order of ``#include blocks`` and also allows the grouping of ``#includes``
- of
diff erent priority. ``SortPriority`` is set to the value of
- ``Priority`` as default if it is not assigned.
+ so that it is generally kept at the beginning of the `#includes`
+ (see [LLVM
+ style](https://llvm.org/docs/CodingStandards.html#include-style)).
+ However, you can also assign negative priorities if you have certain
+ headers that always need to be first.
+
+ There is a third and optional field `SortPriority` which can used while
+ `IncludeBlocks = IBS_Regroup` to define the priority in which
+ `#includes` should be ordered. The value of `Priority` defines the
+ order of `#include blocks` and also allows the grouping of `#includes`
+ of
diff erent priority. `SortPriority` is set to the value of
+ `Priority` as default if it is not assigned.
Each regular expression can be marked as case sensitive with the field
- ``CaseSensitive``, per default it is not.
+ `CaseSensitive`, per default it is not.
To configure this in the .clang-format file, use:
- .. code-block:: yaml
-
- IncludeCategories:
- - Regex: '^"(llvm|llvm-c|clang|clang-c)/'
- Priority: 2
- SortPriority: 2
- CaseSensitive: true
- - Regex: '^((<|")(gtest|gmock|isl|json)/)'
- Priority: 3
- - Regex: '<[[:alnum:].]+>'
- Priority: 4
- - Regex: '.*'
- Priority: 1
- SortPriority: 0
-
-.. _IncludeIsMainRegex:
-
-**IncludeIsMainRegex** (``String``) :versionbadge:`clang-format 3.9` :ref:`¶ <IncludeIsMainRegex>`
- Specify a regular expression of suffixes that are allowed in the
+ ```yaml
+ IncludeCategories:
+ - Regex: '^"(llvm|llvm-c|clang|clang-c)/'
+ Priority: 2
+ SortPriority: 2
+ CaseSensitive: true
+ - Regex: '^((<|")(gtest|gmock|isl|json)/)'
+ Priority: 3
+ - Regex: '<[[:alnum:].]+>'
+ Priority: 4
+ - Regex: '.*'
+ Priority: 1
+ SortPriority: 0
+ ```
+
+(includeismainregex)=
+
+**IncludeIsMainRegex** (`String`) {versionbadge}`clang-format 3.9` {ref}`¶ <IncludeIsMainRegex>`
+
+: Specify a regular expression of suffixes that are allowed in the
file-to-main-include mapping.
When guessing whether a #include is the "main" include (to assign
category 0, see above), use this regex of allowed suffixes to the header
stem. A partial match is done, so that:
- * ``""`` means "arbitrary suffix"
- * ``"$"`` means "no suffix"
+ - `""` means "arbitrary suffix"
+ - `"$"` means "no suffix"
- For example, if configured to ``"(_test)?$"``, then a header a.h would be
+ For example, if configured to `"(_test)?$"`, then a header a.h would be
seen as the "main" include in both a.cc and a_test.cc.
-.. _IncludeIsMainSourceRegex:
+(includeismainsourceregex)=
+
+**IncludeIsMainSourceRegex** (`String`) {versionbadge}`clang-format 10` {ref}`¶ <IncludeIsMainSourceRegex>`
-**IncludeIsMainSourceRegex** (``String``) :versionbadge:`clang-format 10` :ref:`¶ <IncludeIsMainSourceRegex>`
- Specify a regular expression for files being formatted
+: Specify a regular expression for files being formatted
that are allowed to be considered "main" in the
file-to-main-include mapping.
By default, clang-format considers files as "main" only when they end
- with: ``.c``, ``.cc``, ``.cpp``, ``.c++``, ``.cxx``, ``.m`` or ``.mm``
+ with: `.c`, `.cc`, `.cpp`, `.c++`, `.cxx`, `.m` or `.mm`
extensions.
For these files a guessing of "main" include takes place
(to assign category 0, see above). This config option allows for
additional suffixes and extensions for files to be considered as "main".
- For example, if this option is configured to ``(Impl\.hpp)$``,
- then a file ``ClassImpl.hpp`` is considered "main" (in addition to
- ``Class.c``, ``Class.cc``, ``Class.cpp`` and so on) and "main
+ For example, if this option is configured to `(Impl\.hpp)$`,
+ then a file `ClassImpl.hpp` is considered "main" (in addition to
+ `Class.c`, `Class.cc`, `Class.cpp` and so on) and "main
include file" logic will be executed (with *IncludeIsMainRegex* setting
also being respected in later phase). Without this option set,
- ``ClassImpl.hpp`` would not have the main include file put on top
+ `ClassImpl.hpp` would not have the main include file put on top
before any other include.
-.. _IndentAccessModifiers:
+(indentaccessmodifiers)=
-**IndentAccessModifiers** (``Boolean``) :versionbadge:`clang-format 13` :ref:`¶ <IndentAccessModifiers>`
- Specify whether access modifiers should have their own indentation level.
+**IndentAccessModifiers** (`Boolean`) {versionbadge}`clang-format 13` {ref}`¶ <IndentAccessModifiers>`
- When ``false``, access modifiers are indented (or outdented) relative to
- the record members, respecting the ``AccessModifierOffset``. Record
+: Specify whether access modifiers should have their own indentation level.
+
+ When `false`, access modifiers are indented (or outdented) relative to
+ the record members, respecting the `AccessModifierOffset`. Record
members are indented one level below the record.
- When ``true``, access modifiers get their own indentation level. As a
+ When `true`, access modifiers get their own indentation level. As a
consequence, record members are always indented 2 levels below the record,
regardless of the access modifier presence. Value of the
- ``AccessModifierOffset`` is ignored.
-
- .. code-block:: c++
-
- false: true:
- class C { vs. class C {
- class D { class D {
- void bar(); void bar();
- protected: protected:
- D(); D();
- }; };
- public: public:
- C(); C();
- }; };
- void foo() { void foo() {
- return 1; return 1;
- } }
-
-.. _IndentCaseBlocks:
-
-**IndentCaseBlocks** (``Boolean``) :versionbadge:`clang-format 11` :ref:`¶ <IndentCaseBlocks>`
- Indent case label blocks one level from the case label.
-
- When ``false``, the block following the case label uses the same
+ `AccessModifierOffset` is ignored.
+
+ ```c++
+ false: true:
+ class C { vs. class C {
+ class D { class D {
+ void bar(); void bar();
+ protected: protected:
+ D(); D();
+ }; };
+ public: public:
+ C(); C();
+ }; };
+ void foo() { void foo() {
+ return 1; return 1;
+ } }
+ ```
+
+(indentcaseblocks)=
+
+**IndentCaseBlocks** (`Boolean`) {versionbadge}`clang-format 11` {ref}`¶ <IndentCaseBlocks>`
+
+: Indent case label blocks one level from the case label.
+
+ When `false`, the block following the case label uses the same
indentation level as for the case label, treating the case label the same
as an if-statement.
- When ``true``, the block gets indented as a scope block.
-
- .. code-block:: c++
-
- false: true:
- switch (fool) { vs. switch (fool) {
- case 1: { case 1:
- bar(); {
- } break; bar();
- default: { }
- plop(); break;
- } default:
- } {
- plop();
- }
- }
-
-.. _IndentCaseLabels:
-
-**IndentCaseLabels** (``Boolean``) :versionbadge:`clang-format 3.3` :ref:`¶ <IndentCaseLabels>`
- Indent case labels one level from the switch statement.
-
- When ``false``, use the same indentation level as for the switch
+ When `true`, the block gets indented as a scope block.
+
+ ```c++
+ false: true:
+ switch (fool) { vs. switch (fool) {
+ case 1: { case 1:
+ bar(); {
+ } break; bar();
+ default: { }
+ plop(); break;
+ } default:
+ } {
+ plop();
+ }
+ }
+ ```
+
+(indentcaselabels)=
+
+**IndentCaseLabels** (`Boolean`) {versionbadge}`clang-format 3.3` {ref}`¶ <IndentCaseLabels>`
+
+: 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 (except the first block following the case label, which
itself indents the code - unless IndentCaseBlocks is enabled).
- .. code-block:: c++
+ ```c++
+ false: true:
+ switch (fool) { vs. switch (fool) {
+ case 1: case 1:
+ bar(); bar();
+ break; break;
+ default: default:
+ plop(); plop();
+ } }
+ ```
- false: true:
- switch (fool) { vs. switch (fool) {
- case 1: case 1:
- bar(); bar();
- break; break;
- default: default:
- plop(); plop();
- } }
+(indentexportblock)=
-.. _IndentExportBlock:
+**IndentExportBlock** (`Boolean`) {versionbadge}`clang-format 20` {ref}`¶ <IndentExportBlock>`
-**IndentExportBlock** (``Boolean``) :versionbadge:`clang-format 20` :ref:`¶ <IndentExportBlock>`
- If ``true``, clang-format will indent the body of an ``export { ... }``
+: If `true`, clang-format will indent the body of an `export { ... }`
block. This doesn't affect the formatting of anything else related to
exported declarations.
- .. code-block:: c++
+ ```c++
+ true: false:
+ export { vs. export {
+ void foo(); void foo();
+ void bar(); void bar();
+ } }
+ ```
- true: false:
- export { vs. export {
- void foo(); void foo();
- void bar(); void bar();
- } }
+(indentexternblock)=
-.. _IndentExternBlock:
+**IndentExternBlock** (`IndentExternBlockStyle`) {versionbadge}`clang-format 11` {ref}`¶ <IndentExternBlock>`
-**IndentExternBlock** (``IndentExternBlockStyle``) :versionbadge:`clang-format 11` :ref:`¶ <IndentExternBlock>`
- IndentExternBlockStyle is the type of indenting of extern blocks.
+: IndentExternBlockStyle is the type of indenting of extern blocks.
Possible values:
- * ``IEBS_AfterExternBlock`` (in configuration: ``AfterExternBlock``)
+ - `IEBS_AfterExternBlock` (in configuration: `AfterExternBlock`)
Backwards compatible with AfterExternBlock's indenting.
- .. code-block:: c++
-
- IndentExternBlock: AfterExternBlock
- BraceWrapping.AfterExternBlock: true
- extern "C"
- {
- void foo();
- }
-
-
- .. code-block:: c++
+ ```c++
+ IndentExternBlock: AfterExternBlock
+ BraceWrapping.AfterExternBlock: true
+ extern "C"
+ {
+ void foo();
+ }
+ ```
- IndentExternBlock: AfterExternBlock
- BraceWrapping.AfterExternBlock: false
- extern "C" {
- void foo();
- }
+ ```c++
+ IndentExternBlock: AfterExternBlock
+ BraceWrapping.AfterExternBlock: false
+ extern "C" {
+ void foo();
+ }
+ ```
- * ``IEBS_NoIndent`` (in configuration: ``NoIndent``)
+ - `IEBS_NoIndent` (in configuration: `NoIndent`)
Does not indent extern blocks.
- .. code-block:: c++
-
- extern "C" {
- void foo();
- }
+ ```c++
+ extern "C" {
+ void foo();
+ }
+ ```
- * ``IEBS_Indent`` (in configuration: ``Indent``)
+ - `IEBS_Indent` (in configuration: `Indent`)
Indents extern blocks.
- .. code-block:: c++
+ ```c++
+ extern "C" {
+ void foo();
+ }
+ ```
- extern "C" {
- void foo();
- }
+(indentgotolabels)=
-.. _IndentGotoLabels:
+**IndentGotoLabels** (`IndentGotoLabelStyle`) {versionbadge}`clang-format 10` {ref}`¶ <IndentGotoLabels>`
-**IndentGotoLabels** (``IndentGotoLabelStyle``) :versionbadge:`clang-format 10` :ref:`¶ <IndentGotoLabels>`
- The goto label indenting style to use.
+: The goto label indenting style to use.
Possible values:
- * ``IGLS_NoIndent`` (in configuration: ``NoIndent``)
+ - `IGLS_NoIndent` (in configuration: `NoIndent`)
Do not indent goto labels.
- .. code-block:: c++
-
- int f() {
- if (foo()) {
- label1:
- bar();
- }
- label2:
- return 1;
- }
+ ```c++
+ int f() {
+ if (foo()) {
+ label1:
+ bar();
+ }
+ label2:
+ return 1;
+ }
+ ```
- * ``IGLS_OuterIndent`` (in configuration: ``OuterIndent``)
+ - `IGLS_OuterIndent` (in configuration: `OuterIndent`)
Indent goto labels to the enclosing block (previous indenting level).
- .. code-block:: c++
-
- int f() {
- if (foo()) {
- label1:
- bar();
- }
- label2:
- return 1;
- }
+ ```c++
+ int f() {
+ if (foo()) {
+ label1:
+ bar();
+ }
+ label2:
+ return 1;
+ }
+ ```
- * ``IGLS_InnerIndent`` (in configuration: ``InnerIndent``)
+ - `IGLS_InnerIndent` (in configuration: `InnerIndent`)
Indent goto labels to the surrounding statements (current indenting
level).
- .. code-block:: c++
-
- int f() {
- if (foo()) {
- label1:
- bar();
- }
- label2:
- return 1;
- }
+ ```c++
+ int f() {
+ if (foo()) {
+ label1:
+ bar();
+ }
+ label2:
+ return 1;
+ }
+ ```
- * ``IGLS_HalfIndent`` (in configuration: ``HalfIndent``)
+ - `IGLS_HalfIndent` (in configuration: `HalfIndent`)
Indent goto labels to half the indentation of the surrounding code.
If the indentation width is an odd number, it will round up.
- .. code-block:: c++
+ ```c++
+ int f() {
+ if (foo()) {
+ label1:
+ bar();
+ }
+ label2:
+ return 1;
+ }
+ ```
- int f() {
- if (foo()) {
- label1:
- bar();
- }
- label2:
- return 1;
- }
+(indentppdirectives)=
-.. _IndentPPDirectives:
+**IndentPPDirectives** (`PPDirectiveIndentStyle`) {versionbadge}`clang-format 6` {ref}`¶ <IndentPPDirectives>`
-**IndentPPDirectives** (``PPDirectiveIndentStyle``) :versionbadge:`clang-format 6` :ref:`¶ <IndentPPDirectives>`
- The preprocessor directive indenting style to use.
+: The preprocessor directive indenting style to use.
Possible values:
- * ``PPDIS_None`` (in configuration: ``None``)
+ - `PPDIS_None` (in configuration: `None`)
Does not indent any directives.
- .. code-block:: c++
-
- #if FOO
- #if BAR
- #include <foo>
- #endif
- #endif
+ ```c++
+ #if FOO
+ #if BAR
+ #include <foo>
+ #endif
+ #endif
+ ```
- * ``PPDIS_AfterHash`` (in configuration: ``AfterHash``)
+ - `PPDIS_AfterHash` (in configuration: `AfterHash`)
Indents directives after the hash.
- .. code-block:: c++
+ ```c++
+ #if FOO
+ # if BAR
+ # include <foo>
+ # endif
+ #endif
+ ```
- #if FOO
- # if BAR
- # include <foo>
- # endif
- #endif
-
- * ``PPDIS_BeforeHash`` (in configuration: ``BeforeHash``)
+ - `PPDIS_BeforeHash` (in configuration: `BeforeHash`)
Indents directives before the hash.
- .. code-block:: c++
-
- #if FOO
- #if BAR
- #include <foo>
- #endif
- #endif
+ ```c++
+ #if FOO
+ #if BAR
+ #include <foo>
+ #endif
+ #endif
+ ```
- * ``PPDIS_Leave`` (in configuration: ``Leave``)
+ - `PPDIS_Leave` (in configuration: `Leave`)
Leaves indentation of directives as-is.
- .. note::
-
- Ignores ``PPIndentWidth``.
+ :::{note}
+ Ignores `PPIndentWidth`.
+ :::
- .. code-block:: c++
-
- #if FOO
- #if BAR
- #include <foo>
- #endif
+ ```c++
+ #if FOO
+ #if BAR
+ #include <foo>
#endif
+ #endif
+ ```
-.. _IndentRequiresClause:
+(indentrequiresclause)=
-**IndentRequiresClause** (``Boolean``) :versionbadge:`clang-format 15` :ref:`¶ <IndentRequiresClause>`
- Indent the requires clause in a template. This only applies when
- ``RequiresClausePosition`` is ``OwnLine``, ``OwnLineWithBrace``,
- or ``WithFollowing``.
+**IndentRequiresClause** (`Boolean`) {versionbadge}`clang-format 15` {ref}`¶ <IndentRequiresClause>`
- In clang-format 12, 13 and 14 it was named ``IndentRequires``.
+: Indent the requires clause in a template. This only applies when
+ `RequiresClausePosition` is `OwnLine`, `OwnLineWithBrace`,
+ or `WithFollowing`.
- .. code-block:: c++
+ In clang-format 12, 13 and 14 it was named `IndentRequires`.
- true:
- template <typename It>
- requires Iterator<It>
- void sort(It begin, It end) {
- //....
- }
+ ```c++
+ true:
+ template <typename It>
+ requires Iterator<It>
+ void sort(It begin, It end) {
+ //....
+ }
- false:
- template <typename It>
- requires Iterator<It>
- void sort(It begin, It end) {
- //....
- }
+ false:
+ template <typename It>
+ requires Iterator<It>
+ void sort(It begin, It end) {
+ //....
+ }
+ ```
-.. _IndentWidth:
+(indentwidth)=
-**IndentWidth** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <IndentWidth>`
- The number of columns to use for indentation.
+**IndentWidth** (`Unsigned`) {versionbadge}`clang-format 3.7` {ref}`¶ <IndentWidth>`
- .. code-block:: c++
+: The number of columns to use for indentation.
- IndentWidth: 3
+ ```c++
+ IndentWidth: 3
- void f() {
- someFunction();
- if (true, false) {
- f();
- }
+ void f() {
+ someFunction();
+ if (true, false) {
+ f();
}
+ }
+ ```
+
+(indentwrappedfunctionnames)=
-.. _IndentWrappedFunctionNames:
+**IndentWrappedFunctionNames** (`Boolean`) {versionbadge}`clang-format 3.7` {ref}`¶ <IndentWrappedFunctionNames>`
-**IndentWrappedFunctionNames** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <IndentWrappedFunctionNames>`
- Indent if a function definition or declaration is wrapped after the
+: Indent if a function definition or declaration is wrapped after the
type.
- .. code-block:: c++
+ ```c++
+ true:
+ LoooooooooooooooooooooooooooooooooooooooongReturnType
+ LoooooooooooooooooooooooooooooooongFunctionDeclaration();
- true:
- LoooooooooooooooooooooooooooooooooooooooongReturnType
- LoooooooooooooooooooooooooooooooongFunctionDeclaration();
+ false:
+ LoooooooooooooooooooooooooooooooooooooooongReturnType
+ LoooooooooooooooooooooooooooooooongFunctionDeclaration();
+ ```
- false:
- LoooooooooooooooooooooooooooooooooooooooongReturnType
- LoooooooooooooooooooooooooooooooongFunctionDeclaration();
+(insertbraces)=
-.. _InsertBraces:
+**InsertBraces** (`Boolean`) {versionbadge}`clang-format 15` {ref}`¶ <InsertBraces>`
-**InsertBraces** (``Boolean``) :versionbadge:`clang-format 15` :ref:`¶ <InsertBraces>`
- Insert braces after control statements (``if``, ``else``, ``for``, ``do``,
- and ``while``) in C++ unless the control statements are inside macro
+: Insert braces after control statements (`if`, `else`, `for`, `do`,
+ and `while`) in C++ unless the control statements are inside macro
definitions or the braces would enclose preprocessor directives.
- .. warning::
-
- Setting this option to ``true`` could lead to incorrect code formatting
- due to clang-format's lack of complete semantic information. As such,
- extra care should be taken to review code changes made by this option.
-
- .. code-block:: c++
-
- false: true:
+ :::{warning}
+ Setting this option to `true` could lead to incorrect code formatting
+ due to clang-format's lack of complete semantic information. As such,
+ extra care should be taken to review code changes made by this option.
+ :::
+
+ ```c++
+ false: true:
+
+ if (isa<FunctionDecl>(D)) vs. if (isa<FunctionDecl>(D)) {
+ handleFunctionDecl(D); handleFunctionDecl(D);
+ else if (isa<VarDecl>(D)) } else if (isa<VarDecl>(D)) {
+ handleVarDecl(D); handleVarDecl(D);
+ else } else {
+ return; return;
+ }
- if (isa<FunctionDecl>(D)) vs. if (isa<FunctionDecl>(D)) {
- handleFunctionDecl(D); handleFunctionDecl(D);
- else if (isa<VarDecl>(D)) } else if (isa<VarDecl>(D)) {
- handleVarDecl(D); handleVarDecl(D);
- else } else {
- return; return;
+ while (i--) vs. while (i--) {
+ for (auto *A : D.attrs()) for (auto *A : D.attrs()) {
+ handleAttr(A); handleAttr(A);
}
+ }
- while (i--) vs. while (i--) {
- for (auto *A : D.attrs()) for (auto *A : D.attrs()) {
- handleAttr(A); handleAttr(A);
- }
- }
+ do vs. do {
+ --i; --i;
+ while (i); } while (i);
+ ```
+
+(insertnewlineateof)=
- do vs. do {
- --i; --i;
- while (i); } while (i);
+**InsertNewlineAtEOF** (`Boolean`) {versionbadge}`clang-format 16` {ref}`¶ <InsertNewlineAtEOF>`
-.. _InsertNewlineAtEOF:
+: Insert a newline at end of file if missing.
-**InsertNewlineAtEOF** (``Boolean``) :versionbadge:`clang-format 16` :ref:`¶ <InsertNewlineAtEOF>`
- Insert a newline at end of file if missing.
+(inserttrailingcommas)=
-.. _InsertTrailingCommas:
+**InsertTrailingCommas** (`TrailingCommaStyle`) {versionbadge}`clang-format 11` {ref}`¶ <InsertTrailingCommas>`
-**InsertTrailingCommas** (``TrailingCommaStyle``) :versionbadge:`clang-format 11` :ref:`¶ <InsertTrailingCommas>`
- If set to ``TCS_Wrapped`` will insert trailing commas in container
+: If set to `TCS_Wrapped` will insert trailing commas in container
literals (arrays and objects) that wrap across multiple lines.
It is currently only available for JavaScript
- and disabled by default ``TCS_None``.
- ``InsertTrailingCommas`` cannot be used together with ``BinPackArguments``
+ and disabled by default `TCS_None`.
+ `InsertTrailingCommas` cannot be used together with `BinPackArguments`
as inserting the comma disables bin-packing.
- .. code-block:: c++
-
- TSC_Wrapped:
- const someArray = [
- aaaaaaaaaaaaaaaaaaaaaaaaaa,
- aaaaaaaaaaaaaaaaaaaaaaaaaa,
- aaaaaaaaaaaaaaaaaaaaaaaaaa,
- // ^ inserted
- ]
+ ```c++
+ TSC_Wrapped:
+ const someArray = [
+ aaaaaaaaaaaaaaaaaaaaaaaaaa,
+ aaaaaaaaaaaaaaaaaaaaaaaaaa,
+ aaaaaaaaaaaaaaaaaaaaaaaaaa,
+ // ^ inserted
+ ]
+ ```
Possible values:
- * ``TCS_None`` (in configuration: ``None``)
+ - `TCS_None` (in configuration: `None`)
Do not insert trailing commas.
- * ``TCS_Wrapped`` (in configuration: ``Wrapped``)
+ - `TCS_Wrapped` (in configuration: `Wrapped`)
Insert trailing commas in container literals that were wrapped over
multiple lines. Note that this is conceptually incompatible with
bin-packing, because the trailing comma is used as an indicator
@@ -5040,17 +5120,18 @@ the configuration (without a prefix: ``Auto``).
-.. _IntegerLiteralSeparator:
+(integerliteralseparator)=
+
+**IntegerLiteralSeparator** (`IntegerLiteralSeparatorStyle`) {versionbadge}`clang-format 16` {ref}`¶ <IntegerLiteralSeparator>`
-**IntegerLiteralSeparator** (``IntegerLiteralSeparatorStyle``) :versionbadge:`clang-format 16` :ref:`¶ <IntegerLiteralSeparator>`
- Format integer literal separators (``'`` for C/C++ and ``_`` for C#, Java,
+: Format integer literal separators (`'` for C/C++ and `_` for C#, Java,
and JavaScript).
Nested configuration flags:
Separator format of integer literals of
diff erent bases.
- If negative, remove separators. If ``0``, leave the literal as is. If
+ If negative, remove separators. If `0`, leave the literal as is. If
positive, insert separators between digits starting from the rightmost
digit.
@@ -5058,214 +5139,217 @@ the configuration (without a prefix: ``Auto``).
alone, insert separators in decimal literals to separate the digits into
groups of 3, and remove separators in hexadecimal literals.
- .. code-block:: c++
-
- IntegerLiteralSeparator:
- Binary: 0
- Decimal: 3
- Hex: -1
+ ```c++
+ IntegerLiteralSeparator:
+ Binary: 0
+ Decimal: 3
+ Hex: -1
+ ```
You can also specify a minimum number of digits
- (``BinaryMinDigitsInsert``, ``DecimalMinDigitsInsert``, and
- ``HexMinDigitsInsert``) the integer literal must have in order for the
+ (`BinaryMinDigitsInsert`, `DecimalMinDigitsInsert`, and
+ `HexMinDigitsInsert`) the integer literal must have in order for the
separators to be inserted, and a maximum number of digits
- (``BinaryMaxDigitsRemove``, ``DecimalMaxDigitsRemove``, and
- ``HexMaxDigitsRemove``) until the separators are removed. This divides the
+ (`BinaryMaxDigitsRemove`, `DecimalMaxDigitsRemove`, and
+ `HexMaxDigitsRemove`) until the separators are removed. This divides the
literals in 3 regions, always without separator (up until including
- ``xxxMaxDigitsRemove``), maybe with, or without separators (up until
- excluding ``xxxMinDigitsInsert``), and finally always with separators.
-
- .. note::
-
- ``BinaryMinDigits``, ``DecimalMinDigits``, and ``HexMinDigits`` are
- deprecated and renamed to ``BinaryMinDigitsInsert``,
- ``DecimalMinDigitsInsert``, and ``HexMinDigitsInsert``, respectively.
-
- * ``int8_t Binary`` Format separators in binary literals.
-
- .. code-block:: text
-
- /* -1: */ b = 0b100111101101;
- /* 0: */ b = 0b10011'11'0110'1;
- /* 3: */ b = 0b100'111'101'101;
- /* 4: */ b = 0b1001'1110'1101;
-
- * ``int8_t BinaryMinDigitsInsert`` Format separators in binary literals with a minimum number of digits.
-
- .. code-block:: text
-
- // Binary: 3
- // BinaryMinDigitsInsert: 7
- b1 = 0b101101;
- b2 = 0b1'101'101;
-
- * ``int8_t BinaryMaxDigitsRemove`` Remove separators in binary literals with a maximum number of digits.
-
- .. code-block:: text
-
- // Binary: 3
- // BinaryMinDigitsInsert: 7
- // BinaryMaxDigitsRemove: 4
- b0 = 0b1011; // Always removed.
- b1 = 0b101101; // Not added.
- b2 = 0b1'01'101; // Not removed, not corrected.
- b3 = 0b1'101'101; // Always added.
- b4 = 0b10'1101; // Corrected to 0b101'101.
-
- * ``int8_t Decimal`` Format separators in decimal literals.
-
- .. code-block:: text
-
- /* -1: */ d = 18446744073709550592ull;
- /* 0: */ d = 184467'440737'0'95505'92ull;
- /* 3: */ d = 18'446'744'073'709'550'592ull;
-
- * ``int8_t DecimalMinDigitsInsert`` Format separators in decimal literals with a minimum number of digits.
-
- .. code-block:: text
-
- // Decimal: 3
- // DecimalMinDigitsInsert: 5
- d1 = 2023;
- d2 = 10'000;
-
- * ``int8_t DecimalMaxDigitsRemove`` Remove separators in decimal literals with a maximum number of digits.
-
- .. code-block:: text
-
- // Decimal: 3
- // DecimalMinDigitsInsert: 7
- // DecimalMaxDigitsRemove: 4
- d0 = 2023; // Always removed.
- d1 = 123456; // Not added.
- d2 = 1'23'456; // Not removed, not corrected.
- d3 = 5'000'000; // Always added.
- d4 = 1'23'45; // Corrected to 12'345.
-
- * ``int8_t Hex`` Format separators in hexadecimal literals.
-
- .. code-block:: text
-
- /* -1: */ h = 0xDEADBEEFDEADBEEFuz;
- /* 0: */ h = 0xDEAD'BEEF'DE'AD'BEE'Fuz;
- /* 2: */ h = 0xDE'AD'BE'EF'DE'AD'BE'EFuz;
-
- * ``int8_t HexMinDigitsInsert`` Format separators in hexadecimal literals with a minimum number of
+ `xxxMaxDigitsRemove`), maybe with, or without separators (up until
+ excluding `xxxMinDigitsInsert`), and finally always with separators.
+
+ :::{note}
+ `BinaryMinDigits`, `DecimalMinDigits`, and `HexMinDigits` are
+ deprecated and renamed to `BinaryMinDigitsInsert`,
+ `DecimalMinDigitsInsert`, and `HexMinDigitsInsert`, respectively.
+ :::
+
+ - `int8_t Binary` Format separators in binary literals.
+
+ ```text
+ /* -1: */ b = 0b100111101101;
+ /* 0: */ b = 0b10011'11'0110'1;
+ /* 3: */ b = 0b100'111'101'101;
+ /* 4: */ b = 0b1001'1110'1101;
+ ```
+
+ - `int8_t BinaryMinDigitsInsert` Format separators in binary literals with a minimum number of digits.
+
+ ```text
+ // Binary: 3
+ // BinaryMinDigitsInsert: 7
+ b1 = 0b101101;
+ b2 = 0b1'101'101;
+ ```
+
+ - `int8_t BinaryMaxDigitsRemove` Remove separators in binary literals with a maximum number of digits.
+
+ ```text
+ // Binary: 3
+ // BinaryMinDigitsInsert: 7
+ // BinaryMaxDigitsRemove: 4
+ b0 = 0b1011; // Always removed.
+ b1 = 0b101101; // Not added.
+ b2 = 0b1'01'101; // Not removed, not corrected.
+ b3 = 0b1'101'101; // Always added.
+ b4 = 0b10'1101; // Corrected to 0b101'101.
+ ```
+
+ - `int8_t Decimal` Format separators in decimal literals.
+
+ ```text
+ /* -1: */ d = 18446744073709550592ull;
+ /* 0: */ d = 184467'440737'0'95505'92ull;
+ /* 3: */ d = 18'446'744'073'709'550'592ull;
+ ```
+
+ - `int8_t DecimalMinDigitsInsert` Format separators in decimal literals with a minimum number of digits.
+
+ ```text
+ // Decimal: 3
+ // DecimalMinDigitsInsert: 5
+ d1 = 2023;
+ d2 = 10'000;
+ ```
+
+ - `int8_t DecimalMaxDigitsRemove` Remove separators in decimal literals with a maximum number of digits.
+
+ ```text
+ // Decimal: 3
+ // DecimalMinDigitsInsert: 7
+ // DecimalMaxDigitsRemove: 4
+ d0 = 2023; // Always removed.
+ d1 = 123456; // Not added.
+ d2 = 1'23'456; // Not removed, not corrected.
+ d3 = 5'000'000; // Always added.
+ d4 = 1'23'45; // Corrected to 12'345.
+ ```
+
+ - `int8_t Hex` Format separators in hexadecimal literals.
+
+ ```text
+ /* -1: */ h = 0xDEADBEEFDEADBEEFuz;
+ /* 0: */ h = 0xDEAD'BEEF'DE'AD'BEE'Fuz;
+ /* 2: */ h = 0xDE'AD'BE'EF'DE'AD'BE'EFuz;
+ ```
+
+ - `int8_t HexMinDigitsInsert` Format separators in hexadecimal literals with a minimum number of
digits.
- .. code-block:: text
-
- // Hex: 2
- // HexMinDigitsInsert: 6
- h1 = 0xABCDE;
- h2 = 0xAB'CD'EF;
+ ```text
+ // Hex: 2
+ // HexMinDigitsInsert: 6
+ h1 = 0xABCDE;
+ h2 = 0xAB'CD'EF;
+ ```
- * ``int8_t HexMaxDigitsRemove`` Remove separators in hexadecimal literals with a maximum number of
+ - `int8_t HexMaxDigitsRemove` Remove separators in hexadecimal literals with a maximum number of
digits.
- .. code-block:: text
+ ```text
+ // Hex: 2
+ // HexMinDigitsInsert: 6
+ // HexMaxDigitsRemove: 4
+ h0 = 0xAFFE; // Always removed.
+ h1 = 0xABCDE; // Not added.
+ h2 = 0xABC'DE; // Not removed, not corrected.
+ h3 = 0xAB'CD'EF; // Always added.
+ h4 = 0xABCD'E; // Corrected to 0xA'BC'DE.
+ ```
- // Hex: 2
- // HexMinDigitsInsert: 6
- // HexMaxDigitsRemove: 4
- h0 = 0xAFFE; // Always removed.
- h1 = 0xABCDE; // Not added.
- h2 = 0xABC'DE; // Not removed, not corrected.
- h3 = 0xAB'CD'EF; // Always added.
- h4 = 0xABCD'E; // Corrected to 0xA'BC'DE.
+(javaimportgroups)=
-.. _JavaImportGroups:
+**JavaImportGroups** (`List of Strings`) {versionbadge}`clang-format 8` {ref}`¶ <JavaImportGroups>`
-**JavaImportGroups** (``List of Strings``) :versionbadge:`clang-format 8` :ref:`¶ <JavaImportGroups>`
- A vector of prefixes ordered by the desired groups for Java imports.
+: A vector of prefixes ordered by the desired groups for Java imports.
One group's prefix can be a subset of another - the longest prefix is
always matched. Within a group, the imports are ordered lexicographically.
Static imports are grouped separately and follow the same group rules.
By default, static imports are placed before non-static imports,
but this behavior is changed by another option,
- ``SortJavaStaticImport``.
+ `SortJavaStaticImport`.
In the .clang-format configuration file, this can be configured like
in the following yaml example. This will result in imports being
formatted as in the Java example below.
- .. code-block:: yaml
-
- JavaImportGroups: [com.example, com, org]
-
+ ```yaml
+ JavaImportGroups: [com.example, com, org]
+ ```
- .. code-block:: java
+ ```java
+ import static com.example.function1;
- import static com.example.function1;
+ import static com.test.function2;
- import static com.test.function2;
+ import static org.example.function3;
- import static org.example.function3;
+ import com.example.ClassA;
+ import com.example.Test;
+ import com.example.a.ClassB;
- import com.example.ClassA;
- import com.example.Test;
- import com.example.a.ClassB;
+ import com.test.ClassC;
- import com.test.ClassC;
+ import org.example.ClassD;
+ ```
- import org.example.ClassD;
+(javascriptquotes)=
-.. _JavaScriptQuotes:
+**JavaScriptQuotes** (`JavaScriptQuoteStyle`) {versionbadge}`clang-format 3.9` {ref}`¶ <JavaScriptQuotes>`
-**JavaScriptQuotes** (``JavaScriptQuoteStyle``) :versionbadge:`clang-format 3.9` :ref:`¶ <JavaScriptQuotes>`
- The JavaScriptQuoteStyle to use for JavaScript strings.
+: The JavaScriptQuoteStyle to use for JavaScript strings.
Possible values:
- * ``JSQS_Leave`` (in configuration: ``Leave``)
+ - `JSQS_Leave` (in configuration: `Leave`)
Leave string quotes as they are.
- .. code-block:: js
+ ```js
+ string1 = "foo";
+ string2 = 'bar';
+ ```
- string1 = "foo";
- string2 = 'bar';
-
- * ``JSQS_Single`` (in configuration: ``Single``)
+ - `JSQS_Single` (in configuration: `Single`)
Always use single quotes.
- .. code-block:: js
-
- string1 = 'foo';
- string2 = 'bar';
+ ```js
+ string1 = 'foo';
+ string2 = 'bar';
+ ```
- * ``JSQS_Double`` (in configuration: ``Double``)
+ - `JSQS_Double` (in configuration: `Double`)
Always use double quotes.
- .. code-block:: js
+ ```js
+ string1 = "foo";
+ string2 = "bar";
+ ```
- string1 = "foo";
- string2 = "bar";
+(javascriptwrapimports)=
-.. _JavaScriptWrapImports:
+**JavaScriptWrapImports** (`Boolean`) {versionbadge}`clang-format 3.9` {ref}`¶ <JavaScriptWrapImports>`
-**JavaScriptWrapImports** (``Boolean``) :versionbadge:`clang-format 3.9` :ref:`¶ <JavaScriptWrapImports>`
- Whether to wrap JavaScript import/export statements.
+: Whether to wrap JavaScript import/export statements.
- .. code-block:: js
+ ```js
+ true:
+ import {
+ VeryLongImportsAreAnnoying,
+ VeryLongImportsAreAnnoying,
+ VeryLongImportsAreAnnoying,
+ } from "some/module.js"
- true:
- import {
- VeryLongImportsAreAnnoying,
- VeryLongImportsAreAnnoying,
- VeryLongImportsAreAnnoying,
- } from "some/module.js"
+ false:
+ import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js"
+ ```
- false:
- import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js"
+(keepemptylines)=
-.. _KeepEmptyLines:
+**KeepEmptyLines** (`KeepEmptyLinesStyle`) {versionbadge}`clang-format 19` {ref}`¶ <KeepEmptyLines>`
-**KeepEmptyLines** (``KeepEmptyLinesStyle``) :versionbadge:`clang-format 19` :ref:`¶ <KeepEmptyLines>`
- Which empty lines are kept. See ``MaxEmptyLinesToKeep`` for how many
+: Which empty lines are kept. See `MaxEmptyLinesToKeep` for how many
consecutive empty lines are kept.
Nested configuration flags:
@@ -5275,348 +5359,361 @@ the configuration (without a prefix: ``Auto``).
For example, the config below will remove empty lines at start of the
file, end of the file, and start of blocks.
+ ```c++
+ KeepEmptyLines:
+ AtEndOfFile: false
+ AtStartOfBlock: false
+ AtStartOfFile: false
+ ```
- .. code-block:: c++
+ - `bool AtEndOfFile` Keep empty lines at end of file.
- KeepEmptyLines:
- AtEndOfFile: false
- AtStartOfBlock: false
- AtStartOfFile: false
+ - `bool AtStartOfBlock` Keep empty lines at start of a block.
- * ``bool AtEndOfFile`` Keep empty lines at end of file.
+ ```c++
+ true: false:
+ if (foo) { vs. if (foo) {
+ bar();
+ bar(); }
+ }
+ ```
- * ``bool AtStartOfBlock`` Keep empty lines at start of a block.
+ - `bool AtStartOfFile` Keep empty lines at start of file.
- .. code-block:: c++
- true: false:
- if (foo) { vs. if (foo) {
- bar();
- bar(); }
- }
+(keepemptylinesateof)=
- * ``bool AtStartOfFile`` Keep empty lines at start of file.
+**KeepEmptyLinesAtEOF** (`Boolean`) {versionbadge}`clang-format 17` {ref}`¶ <KeepEmptyLinesAtEOF>`
+: This option is **deprecated**. See `AtEndOfFile` of `KeepEmptyLines`.
-.. _KeepEmptyLinesAtEOF:
+(keepemptylinesatthestartofblocks)=
-**KeepEmptyLinesAtEOF** (``Boolean``) :versionbadge:`clang-format 17` :ref:`¶ <KeepEmptyLinesAtEOF>`
- This option is **deprecated**. See ``AtEndOfFile`` of ``KeepEmptyLines``.
+**KeepEmptyLinesAtTheStartOfBlocks** (`Boolean`) {versionbadge}`clang-format 3.7` {ref}`¶ <KeepEmptyLinesAtTheStartOfBlocks>`
-.. _KeepEmptyLinesAtTheStartOfBlocks:
+: This option is **deprecated**. See `AtStartOfBlock` of
+ `KeepEmptyLines`.
-**KeepEmptyLinesAtTheStartOfBlocks** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <KeepEmptyLinesAtTheStartOfBlocks>`
- This option is **deprecated**. See ``AtStartOfBlock`` of
- ``KeepEmptyLines``.
+(keepformfeed)=
-.. _KeepFormFeed:
+**KeepFormFeed** (`Boolean`) {versionbadge}`clang-format 20` {ref}`¶ <KeepFormFeed>`
-**KeepFormFeed** (``Boolean``) :versionbadge:`clang-format 20` :ref:`¶ <KeepFormFeed>`
- Keep the form feed character if it's immediately preceded and followed by
+: Keep the form feed character if it's immediately preceded and followed by
a newline. Multiple form feeds and newlines within a whitespace range are
replaced with a single newline and form feed followed by the remaining
newlines. (See
www.gnu.org/prep/standards/html_node/Formatting.html#:~:text=formfeed.)
-.. _LambdaBodyIndentation:
+(lambdabodyindentation)=
-**LambdaBodyIndentation** (``LambdaBodyIndentationKind``) :versionbadge:`clang-format 13` :ref:`¶ <LambdaBodyIndentation>`
- The indentation style of lambda bodies. ``Signature`` (the default)
+**LambdaBodyIndentation** (`LambdaBodyIndentationKind`) {versionbadge}`clang-format 13` {ref}`¶ <LambdaBodyIndentation>`
+
+: The indentation style of lambda bodies. `Signature` (the default)
causes the lambda body to be indented one additional level relative to
- the indentation level of the signature. ``OuterScope`` forces the lambda
+ the indentation level of the signature. `OuterScope` forces the lambda
body to be indented one additional level relative to the parent scope
containing the lambda signature.
Possible values:
- * ``LBI_Signature`` (in configuration: ``Signature``)
+ - `LBI_Signature` (in configuration: `Signature`)
Align lambda body relative to the lambda signature. This is the default.
- .. code-block:: c++
-
- someMethod(
- [](SomeReallyLongLambdaSignatureArgument foo) {
- return;
- });
+ ```c++
+ someMethod(
+ [](SomeReallyLongLambdaSignatureArgument foo) {
+ return;
+ });
+ ```
- * ``LBI_OuterScope`` (in configuration: ``OuterScope``)
+ - `LBI_OuterScope` (in configuration: `OuterScope`)
For statements within block scope, align lambda body relative to the
indentation level of the outer scope the lambda signature resides in.
- .. code-block:: c++
-
- someMethod(
- [](SomeReallyLongLambdaSignatureArgument foo) {
- return;
- });
+ ```c++
+ someMethod(
+ [](SomeReallyLongLambdaSignatureArgument foo) {
+ return;
+ });
- someMethod(someOtherMethod(
- [](SomeReallyLongLambdaSignatureArgument foo) {
- return;
- }));
+ someMethod(someOtherMethod(
+ [](SomeReallyLongLambdaSignatureArgument foo) {
+ return;
+ }));
+ ```
-.. _Language:
+(language)=
-**Language** (``LanguageKind``) :versionbadge:`clang-format 3.5` :ref:`¶ <Language>`
- The language that this format style targets.
+**Language** (`LanguageKind`) {versionbadge}`clang-format 3.5` {ref}`¶ <Language>`
- .. note::
+: The language that this format style targets.
- You can specify the language (``C``, ``Cpp``, or ``ObjC``) for ``.h``
- files by adding a ``// clang-format Language:`` line before the first
- non-comment (and non-empty) line, e.g. ``// clang-format Language: Cpp``.
+ :::{note}
+ You can specify the language (`C`, `Cpp`, or `ObjC`) for `.h`
+ files by adding a `// clang-format Language:` line before the first
+ non-comment (and non-empty) line, e.g. `// clang-format Language: Cpp`.
+ :::
Possible values:
- * ``LK_None`` (in configuration: ``None``)
+ - `LK_None` (in configuration: `None`)
Do not use.
- * ``LK_C`` (in configuration: ``C``)
+ - `LK_C` (in configuration: `C`)
Should be used for C.
- * ``LK_Cpp`` (in configuration: ``Cpp``)
+ - `LK_Cpp` (in configuration: `Cpp`)
Should be used for C++.
- * ``LK_CSharp`` (in configuration: ``CSharp``)
+ - `LK_CSharp` (in configuration: `CSharp`)
Should be used for C#.
- * ``LK_Java`` (in configuration: ``Java``)
+ - `LK_Java` (in configuration: `Java`)
Should be used for Java.
- * ``LK_JavaScript`` (in configuration: ``JavaScript``)
+ - `LK_JavaScript` (in configuration: `JavaScript`)
Should be used for JavaScript.
- * ``LK_Json`` (in configuration: ``Json``)
+ - `LK_Json` (in configuration: `Json`)
Should be used for JSON.
- * ``LK_ObjC`` (in configuration: ``ObjC``)
+ - `LK_ObjC` (in configuration: `ObjC`)
Should be used for Objective-C, Objective-C++.
- * ``LK_Proto`` (in configuration: ``Proto``)
- Should be used for Protocol Buffers
- (https://developers.google.com/protocol-buffers/).
+ - `LK_Proto` (in configuration: `Proto`)
+ Should be used for [Protocol Buffers](https://protobuf.dev/)
- * ``LK_TableGen`` (in configuration: ``TableGen``)
+ - `LK_TableGen` (in configuration: `TableGen`)
Should be used for TableGen code.
- * ``LK_TextProto`` (in configuration: ``TextProto``)
- Should be used for Protocol Buffer messages in text format
- (https://developers.google.com/protocol-buffers/).
+ - `LK_TextProto` (in configuration: `TextProto`)
+ Should be used for [Protocol Buffer](https://protobuf.dev/) messages in
+ text format
- * ``LK_Verilog`` (in configuration: ``Verilog``)
+ - `LK_Verilog` (in configuration: `Verilog`)
Should be used for Verilog and SystemVerilog.
https://standards.ieee.org/ieee/1800/6700/
https://sci-hub.st/10.1109/IEEESTD.2018.8299595
-.. _LineEnding:
+(lineending)=
-**LineEnding** (``LineEndingStyle``) :versionbadge:`clang-format 16` :ref:`¶ <LineEnding>`
- Line ending style (``\n`` or ``\r\n``) to use.
+**LineEnding** (`LineEndingStyle`) {versionbadge}`clang-format 16` {ref}`¶ <LineEnding>`
+
+: Line ending style (`\n` or `\r\n`) to use.
Possible values:
- * ``LE_LF`` (in configuration: ``LF``)
- Use ``\n``.
+ - `LE_LF` (in configuration: `LF`)
+ Use `\n`.
+
+ - `LE_CRLF` (in configuration: `CRLF`)
+ Use `\r\n`.
- * ``LE_CRLF`` (in configuration: ``CRLF``)
- Use ``\r\n``.
+ - `LE_DeriveLF` (in configuration: `DeriveLF`)
+ Use `\n` unless the input has more lines ending in `\r\n`.
- * ``LE_DeriveLF`` (in configuration: ``DeriveLF``)
- Use ``\n`` unless the input has more lines ending in ``\r\n``.
+ - `LE_DeriveCRLF` (in configuration: `DeriveCRLF`)
+ Use `\r\n` unless the input has more lines ending in `\n`.
- * ``LE_DeriveCRLF`` (in configuration: ``DeriveCRLF``)
- Use ``\r\n`` unless the input has more lines ending in ``\n``.
+(macroblockbegin)=
-.. _MacroBlockBegin:
+**MacroBlockBegin** (`String`) {versionbadge}`clang-format 3.7` {ref}`¶ <MacroBlockBegin>`
-**MacroBlockBegin** (``String``) :versionbadge:`clang-format 3.7` :ref:`¶ <MacroBlockBegin>`
- A regular expression matching macros that start a block.
+: A regular expression matching macros that start a block.
- .. code-block:: c++
+ ```c++
+ # With:
+ MacroBlockBegin: "^NS_MAP_BEGIN|\
+ NS_TABLE_HEAD$"
+ MacroBlockEnd: "^\
+ NS_MAP_END|\
+ NS_TABLE_.*_END$"
- # With:
- MacroBlockBegin: "^NS_MAP_BEGIN|\
- NS_TABLE_HEAD$"
- MacroBlockEnd: "^\
- NS_MAP_END|\
- NS_TABLE_.*_END$"
+ NS_MAP_BEGIN
+ foo();
+ NS_MAP_END
- NS_MAP_BEGIN
- foo();
- NS_MAP_END
+ NS_TABLE_HEAD
+ bar();
+ NS_TABLE_FOO_END
- NS_TABLE_HEAD
- bar();
- NS_TABLE_FOO_END
+ # Without:
+ NS_MAP_BEGIN
+ foo();
+ NS_MAP_END
- # Without:
- NS_MAP_BEGIN
- foo();
- NS_MAP_END
+ NS_TABLE_HEAD
+ bar();
+ NS_TABLE_FOO_END
+ ```
- NS_TABLE_HEAD
- bar();
- NS_TABLE_FOO_END
+(macroblockend)=
-.. _MacroBlockEnd:
+**MacroBlockEnd** (`String`) {versionbadge}`clang-format 3.7` {ref}`¶ <MacroBlockEnd>`
-**MacroBlockEnd** (``String``) :versionbadge:`clang-format 3.7` :ref:`¶ <MacroBlockEnd>`
- A regular expression matching macros that end a block.
+: A regular expression matching macros that end a block.
-.. _Macros:
+(macros)=
-**Macros** (``List of Strings``) :versionbadge:`clang-format 17` :ref:`¶ <Macros>`
- A list of macros of the form ``<definition>=<expansion>`` .
+**Macros** (`List of Strings`) {versionbadge}`clang-format 17` {ref}`¶ <Macros>`
+
+: A list of macros of the form `<definition>=<expansion>` .
Code will be parsed with macros expanded, in order to determine how to
interpret and format the macro arguments.
For example, the code:
- .. code-block:: c++
-
- A(a*b);
+ ```c++
+ A(a*b);
+ ```
will usually be interpreted as a call to a function A, and the
- multiplication expression will be formatted as ``a * b``.
+ multiplication expression will be formatted as `a * b`.
If we specify the macro definition:
- .. code-block:: yaml
-
- Macros:
- - A(x)=x
+ ```yaml
+ Macros:
+ - A(x)=x
+ ```
the code will now be parsed as a declaration of the variable b of type a*,
- and formatted as ``a* b`` (depending on pointer-binding rules).
+ and formatted as `a* b` (depending on pointer-binding rules).
Features and restrictions:
- * Both function-like macros and object-like macros are supported.
- * Macro arguments must be used exactly once in the expansion.
- * No recursive expansion; macros referencing other macros will be
- ignored.
- * Overloading by arity is supported: for example, given the macro
- definitions A=x, A()=y, A(a)=a
+ - Both function-like macros and object-like macros are supported.
+ - Macro arguments must be used exactly once in the expansion.
+ - No recursive expansion; macros referencing other macros will be
+ ignored.
+ - Overloading by arity is supported: for example, given the macro
+ definitions A=x, A()=y, A(a)=a
+
+ ```c++
+ A; -> x;
+ A(); -> y;
+ A(z); -> z;
+ A(a, b); // will not be expanded.
+ ```
- .. code-block:: c++
+(macrosskippedbyremoveparentheses)=
- A; -> x;
- A(); -> y;
- A(z); -> z;
- A(a, b); // will not be expanded.
+**MacrosSkippedByRemoveParentheses** (`List of Strings`) {versionbadge}`clang-format 21` {ref}`¶ <MacrosSkippedByRemoveParentheses>`
-.. _MacrosSkippedByRemoveParentheses:
+: A vector of function-like macros whose invocations should be skipped by
+ `RemoveParentheses`.
-**MacrosSkippedByRemoveParentheses** (``List of Strings``) :versionbadge:`clang-format 21` :ref:`¶ <MacrosSkippedByRemoveParentheses>`
- A vector of function-like macros whose invocations should be skipped by
- ``RemoveParentheses``.
+(mainincludechar)=
-.. _MainIncludeChar:
+**MainIncludeChar** (`MainIncludeCharDiscriminator`) {versionbadge}`clang-format 19` {ref}`¶ <MainIncludeChar>`
-**MainIncludeChar** (``MainIncludeCharDiscriminator``) :versionbadge:`clang-format 19` :ref:`¶ <MainIncludeChar>`
- When guessing whether a #include is the "main" include, only the include
+: When guessing whether a #include is the "main" include, only the include
directives that use the specified character are considered.
Possible values:
- * ``MICD_Quote`` (in configuration: ``Quote``)
- Main include uses quotes: ``#include "foo.hpp"`` (the default).
+ - `MICD_Quote` (in configuration: `Quote`)
+ Main include uses quotes: `#include "foo.hpp"` (the default).
- * ``MICD_AngleBracket`` (in configuration: ``AngleBracket``)
- Main include uses angle brackets: ``#include <foo.hpp>``.
+ - `MICD_AngleBracket` (in configuration: `AngleBracket`)
+ Main include uses angle brackets: `#include <foo.hpp>`.
- * ``MICD_Any`` (in configuration: ``Any``)
+ - `MICD_Any` (in configuration: `Any`)
Main include uses either quotes or angle brackets.
-.. _MaxEmptyLinesToKeep:
+(maxemptylinestokeep)=
-**MaxEmptyLinesToKeep** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <MaxEmptyLinesToKeep>`
- The maximum number of consecutive empty lines to keep.
+**MaxEmptyLinesToKeep** (`Unsigned`) {versionbadge}`clang-format 3.7` {ref}`¶ <MaxEmptyLinesToKeep>`
- .. code-block:: c++
+: The maximum number of consecutive empty lines to keep.
- MaxEmptyLinesToKeep: 1 vs. MaxEmptyLinesToKeep: 0
- int f() { int f() {
- int = 1; int i = 1;
- i = foo();
- i = foo(); return i;
- }
- return i;
- }
+ ```c++
+ MaxEmptyLinesToKeep: 1 vs. MaxEmptyLinesToKeep: 0
+ int f() { int f() {
+ int = 1; int i = 1;
+ i = foo();
+ i = foo(); return i;
+ }
+ return i;
+ }
+ ```
+
+(namespaceindentation)=
-.. _NamespaceIndentation:
+**NamespaceIndentation** (`NamespaceIndentationKind`) {versionbadge}`clang-format 3.7` {ref}`¶ <NamespaceIndentation>`
-**NamespaceIndentation** (``NamespaceIndentationKind``) :versionbadge:`clang-format 3.7` :ref:`¶ <NamespaceIndentation>`
- The indentation used for namespaces.
+: The indentation used for namespaces.
Possible values:
- * ``NI_None`` (in configuration: ``None``)
+ - `NI_None` (in configuration: `None`)
Don't indent in namespaces.
- .. code-block:: c++
-
- namespace out {
- int i;
- namespace in {
- int i;
- }
- }
+ ```c++
+ namespace out {
+ int i;
+ namespace in {
+ int i;
+ }
+ }
+ ```
- * ``NI_Inner`` (in configuration: ``Inner``)
+ - `NI_Inner` (in configuration: `Inner`)
Indent only in inner namespaces (nested in other namespaces).
- .. code-block:: c++
-
- namespace out {
- int i;
- namespace in {
- int i;
- }
- }
+ ```c++
+ namespace out {
+ int i;
+ namespace in {
+ int i;
+ }
+ }
+ ```
- * ``NI_All`` (in configuration: ``All``)
+ - `NI_All` (in configuration: `All`)
Indent in all namespaces.
- .. code-block:: c++
+ ```c++
+ namespace out {
+ int i;
+ namespace in {
+ int i;
+ }
+ }
+ ```
- namespace out {
- int i;
- namespace in {
- int i;
- }
- }
+(namespacemacros)=
-.. _NamespaceMacros:
+**NamespaceMacros** (`List of Strings`) {versionbadge}`clang-format 9` {ref}`¶ <NamespaceMacros>`
-**NamespaceMacros** (``List of Strings``) :versionbadge:`clang-format 9` :ref:`¶ <NamespaceMacros>`
- A vector of macros which are used to open namespace blocks.
+: A vector of macros which are used to open namespace blocks.
These are expected to be macros of the form:
- .. code-block:: c++
-
- NAMESPACE(<namespace-name>, ...) {
- <namespace-content>
- }
+ ```c++
+ NAMESPACE(<namespace-name>, ...) {
+ <namespace-content>
+ }
+ ```
For example: TESTSUITE
-.. _NumericLiteralCase:
+(numericliteralcase)=
-**NumericLiteralCase** (``NumericLiteralCaseStyle``) :versionbadge:`clang-format 22` :ref:`¶ <NumericLiteralCase>`
- Capitalization style for numeric literals.
+**NumericLiteralCase** (`NumericLiteralCaseStyle`) {versionbadge}`clang-format 22` {ref}`¶ <NumericLiteralCase>`
+
+: Capitalization style for numeric literals.
Nested configuration flags:
@@ -5626,423 +5723,434 @@ the configuration (without a prefix: ``Auto``).
hexadecimal digits in lowercase, reformat numeric literal prefixes in
uppercase, and reformat suffixes in lowercase.
- .. code-block:: c++
-
- NumericLiteralCase:
- ExponentLetter: Leave
- HexDigit: Lower
- Prefix: Upper
- Suffix: Lower
+ ```c++
+ NumericLiteralCase:
+ ExponentLetter: Leave
+ HexDigit: Lower
+ Prefix: Upper
+ Suffix: Lower
+ ```
- * ``NumericLiteralComponentStyle ExponentLetter``
+ - `NumericLiteralComponentStyle ExponentLetter`
Format floating point exponent separator letter case.
- .. code-block:: c++
-
- float a = 6.02e23 + 1.0E10; // Leave
- float a = 6.02E23 + 1.0E10; // Upper
- float a = 6.02e23 + 1.0e10; // Lower
+ ```c++
+ float a = 6.02e23 + 1.0E10; // Leave
+ float a = 6.02E23 + 1.0E10; // Upper
+ float a = 6.02e23 + 1.0e10; // Lower
+ ```
Possible values:
- * ``NLCS_Leave`` (in configuration: ``Leave``)
+ - `NLCS_Leave` (in configuration: `Leave`)
Leave this component of the literal as is.
- * ``NLCS_Upper`` (in configuration: ``Upper``)
+ - `NLCS_Upper` (in configuration: `Upper`)
Format this component with uppercase characters.
- * ``NLCS_Lower`` (in configuration: ``Lower``)
+ - `NLCS_Lower` (in configuration: `Lower`)
Format this component with lowercase characters.
- * ``NumericLiteralComponentStyle HexDigit``
+ - `NumericLiteralComponentStyle HexDigit`
Format hexadecimal digit case.
- .. code-block:: c++
-
- a = 0xaBcDeF; // Leave
- a = 0xABCDEF; // Upper
- a = 0xabcdef; // Lower
+ ```c++
+ a = 0xaBcDeF; // Leave
+ a = 0xABCDEF; // Upper
+ a = 0xabcdef; // Lower
+ ```
Possible values:
- * ``NLCS_Leave`` (in configuration: ``Leave``)
+ - `NLCS_Leave` (in configuration: `Leave`)
Leave this component of the literal as is.
- * ``NLCS_Upper`` (in configuration: ``Upper``)
+ - `NLCS_Upper` (in configuration: `Upper`)
Format this component with uppercase characters.
- * ``NLCS_Lower`` (in configuration: ``Lower``)
+ - `NLCS_Lower` (in configuration: `Lower`)
Format this component with lowercase characters.
- * ``NumericLiteralComponentStyle Prefix``
+ - `NumericLiteralComponentStyle Prefix`
Format integer prefix case.
- .. code-block:: c++
-
- a = 0XF0 | 0b1; // Leave
- a = 0XF0 | 0B1; // Upper
- a = 0xF0 | 0b1; // Lower
+ ```c++
+ a = 0XF0 | 0b1; // Leave
+ a = 0XF0 | 0B1; // Upper
+ a = 0xF0 | 0b1; // Lower
+ ```
Possible values:
- * ``NLCS_Leave`` (in configuration: ``Leave``)
+ - `NLCS_Leave` (in configuration: `Leave`)
Leave this component of the literal as is.
- * ``NLCS_Upper`` (in configuration: ``Upper``)
+ - `NLCS_Upper` (in configuration: `Upper`)
Format this component with uppercase characters.
- * ``NLCS_Lower`` (in configuration: ``Lower``)
+ - `NLCS_Lower` (in configuration: `Lower`)
Format this component with lowercase characters.
- * ``NumericLiteralComponentStyle Suffix``
+ - `NumericLiteralComponentStyle Suffix`
Format suffix case. This option excludes case-sensitive reserved
- suffixes, such as ``min`` in C++.
-
- .. code-block:: c++
+ suffixes, such as `min` in C++.
- a = 1uLL; // Leave
- a = 1ULL; // Upper
- a = 1ull; // Lower
+ ```c++
+ a = 1uLL; // Leave
+ a = 1ULL; // Upper
+ a = 1ull; // Lower
+ ```
Possible values:
- * ``NLCS_Leave`` (in configuration: ``Leave``)
+ - `NLCS_Leave` (in configuration: `Leave`)
Leave this component of the literal as is.
- * ``NLCS_Upper`` (in configuration: ``Upper``)
+ - `NLCS_Upper` (in configuration: `Upper`)
Format this component with uppercase characters.
- * ``NLCS_Lower`` (in configuration: ``Lower``)
+ - `NLCS_Lower` (in configuration: `Lower`)
Format this component with lowercase characters.
-.. _ObjCBinPackProtocolList:
+(objcbinpackprotocollist)=
-**ObjCBinPackProtocolList** (``BinPackStyle``) :versionbadge:`clang-format 7` :ref:`¶ <ObjCBinPackProtocolList>`
- Controls bin-packing Objective-C protocol conformance list
- items into as few lines as possible when they go over ``ColumnLimit``.
+**ObjCBinPackProtocolList** (`BinPackStyle`) {versionbadge}`clang-format 7` {ref}`¶ <ObjCBinPackProtocolList>`
- If ``Auto`` (the default), delegates to the value in
- ``BinPackParameters``. If that is ``BinPack``, bin-packs Objective-C
+: Controls bin-packing Objective-C protocol conformance list
+ items into as few lines as possible when they go over `ColumnLimit`.
+
+ If `Auto` (the default), delegates to the value in
+ `BinPackParameters`. If that is `BinPack`, bin-packs Objective-C
protocol conformance list items into as few lines as possible
- whenever they go over ``ColumnLimit``.
+ whenever they go over `ColumnLimit`.
- If ``Always``, always bin-packs Objective-C protocol conformance
+ If `Always`, always bin-packs Objective-C protocol conformance
list items into as few lines as possible whenever they go over
- ``ColumnLimit``.
-
- If ``Never``, lays out Objective-C protocol conformance list items
- onto individual lines whenever they go over ``ColumnLimit``.
+ `ColumnLimit`.
+ If `Never`, lays out Objective-C protocol conformance list items
+ onto individual lines whenever they go over `ColumnLimit`.
- .. code-block:: objc
-
- Always (or Auto, if BinPackParameters==BinPack):
- @interface ccccccccccccc () <
- ccccccccccccc, ccccccccccccc,
- ccccccccccccc, ccccccccccccc> {
- }
+ ```objc
+ Always (or Auto, if BinPackParameters==BinPack):
+ @interface ccccccccccccc () <
+ ccccccccccccc, ccccccccccccc,
+ ccccccccccccc, ccccccccccccc> {
+ }
- Never (or Auto, if BinPackParameters!=BinPack):
- @interface ddddddddddddd () <
- ddddddddddddd,
- ddddddddddddd,
- ddddddddddddd,
- ddddddddddddd> {
- }
+ Never (or Auto, if BinPackParameters!=BinPack):
+ @interface ddddddddddddd () <
+ ddddddddddddd,
+ ddddddddddddd,
+ ddddddddddddd,
+ ddddddddddddd> {
+ }
+ ```
Possible values:
- * ``BPS_Auto`` (in configuration: ``Auto``)
+ - `BPS_Auto` (in configuration: `Auto`)
Automatically determine parameter bin-packing behavior.
- * ``BPS_Always`` (in configuration: ``Always``)
+ - `BPS_Always` (in configuration: `Always`)
Always bin-pack parameters.
- * ``BPS_Never`` (in configuration: ``Never``)
+ - `BPS_Never` (in configuration: `Never`)
Never bin-pack parameters.
-.. _ObjCBlockIndentWidth:
-
-**ObjCBlockIndentWidth** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <ObjCBlockIndentWidth>`
- The number of characters to use for indentation of ObjC blocks.
+(objcblockindentwidth)=
- .. code-block:: objc
+**ObjCBlockIndentWidth** (`Unsigned`) {versionbadge}`clang-format 3.7` {ref}`¶ <ObjCBlockIndentWidth>`
- ObjCBlockIndentWidth: 4
+: The number of characters to use for indentation of ObjC blocks.
- [operation setCompletionBlock:^{
- [self onOperationDone];
- }];
+ ```objc
+ ObjCBlockIndentWidth: 4
-.. _ObjCBreakBeforeNestedBlockParam:
+ [operation setCompletionBlock:^{
+ [self onOperationDone];
+ }];
+ ```
-**ObjCBreakBeforeNestedBlockParam** (``Boolean``) :versionbadge:`clang-format 11` :ref:`¶ <ObjCBreakBeforeNestedBlockParam>`
- Break parameters list into lines when there is nested block
- parameters in a function call.
-
- .. code-block:: c++
+(objcbreakbeforenestedblockparam)=
- false:
- - (void)_aMethod
- {
- [self.test1 t:self w:self callback:^(typeof(self) self, NSNumber
- *u, NSNumber *v) {
- u = c;
- }]
- }
- true:
- - (void)_aMethod
- {
- [self.test1 t:self
- w:self
- callback:^(typeof(self) self, NSNumber *u, NSNumber *v) {
- u = c;
- }]
- }
+**ObjCBreakBeforeNestedBlockParam** (`Boolean`) {versionbadge}`clang-format 11` {ref}`¶ <ObjCBreakBeforeNestedBlockParam>`
-.. _ObjCPropertyAttributeOrder:
+: Break parameters list into lines when there is nested block
+ parameters in a function call.
-**ObjCPropertyAttributeOrder** (``List of Strings``) :versionbadge:`clang-format 18` :ref:`¶ <ObjCPropertyAttributeOrder>`
- The order in which ObjC property attributes should appear.
+ ```c++
+ false:
+ - (void)_aMethod
+ {
+ [self.test1 t:self w:self callback:^(typeof(self) self, NSNumber
+ *u, NSNumber *v) {
+ u = c;
+ }]
+ }
+ true:
+ - (void)_aMethod
+ {
+ [self.test1 t:self
+ w:self
+ callback:^(typeof(self) self, NSNumber *u, NSNumber *v) {
+ u = c;
+ }]
+ }
+ ```
+
+(objcpropertyattributeorder)=
+
+**ObjCPropertyAttributeOrder** (`List of Strings`) {versionbadge}`clang-format 18` {ref}`¶ <ObjCPropertyAttributeOrder>`
+
+: The order in which ObjC property attributes should appear.
Attributes in code will be sorted in the order specified. Any attributes
encountered that are not mentioned in this array will be sorted last, in
stable order. Comments between attributes will leave the attributes
untouched.
- .. warning::
+ :::{warning}
+ Using this option could lead to incorrect code formatting due to
+ clang-format's lack of complete semantic information. As such, extra
+ care should be taken to review code changes made by this option.
+ :::
- Using this option could lead to incorrect code formatting due to
- clang-format's lack of complete semantic information. As such, extra
- care should be taken to review code changes made by this option.
+ ```yaml
+ ObjCPropertyAttributeOrder: [
+ class, direct,
+ atomic, nonatomic,
+ assign, retain, strong, copy, weak, unsafe_unretained,
+ readonly, readwrite, getter, setter,
+ nullable, nonnull, null_resettable, null_unspecified
+ ]
+ ```
- .. code-block:: yaml
+(objcspaceaftermethoddeclarationprefix)=
- ObjCPropertyAttributeOrder: [
- class, direct,
- atomic, nonatomic,
- assign, retain, strong, copy, weak, unsafe_unretained,
- readonly, readwrite, getter, setter,
- nullable, nonnull, null_resettable, null_unspecified
- ]
+**ObjCSpaceAfterMethodDeclarationPrefix** (`Boolean`) {versionbadge}`clang-format 23` {ref}`¶ <ObjCSpaceAfterMethodDeclarationPrefix>`
-.. _ObjCSpaceAfterMethodDeclarationPrefix:
-
-**ObjCSpaceAfterMethodDeclarationPrefix** (``Boolean``) :versionbadge:`clang-format 23` :ref:`¶ <ObjCSpaceAfterMethodDeclarationPrefix>`
- Add or remove a space between the '-'/'+' and the return type in
+: Add or remove a space between the '-'/'+' and the return type in
Objective-C method declarations. i.e
- .. code-block:: objc
+ ```objc
+ false: true:
+
+ -(void)method vs. - (void)method
+ ```
- false: true:
+(objcspaceafterproperty)=
- -(void)method vs. - (void)method
+**ObjCSpaceAfterProperty** (`Boolean`) {versionbadge}`clang-format 3.7` {ref}`¶ <ObjCSpaceAfterProperty>`
-.. _ObjCSpaceAfterProperty:
+: Add a space after `@property` in Objective-C, i.e. use
+ `@property (readonly)` instead of `@property(readonly)`.
-**ObjCSpaceAfterProperty** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <ObjCSpaceAfterProperty>`
- Add a space after ``@property`` in Objective-C, i.e. use
- ``@property (readonly)`` instead of ``@property(readonly)``.
+(objcspacebeforeprotocollist)=
-.. _ObjCSpaceBeforeProtocolList:
+**ObjCSpaceBeforeProtocolList** (`Boolean`) {versionbadge}`clang-format 3.7` {ref}`¶ <ObjCSpaceBeforeProtocolList>`
-**ObjCSpaceBeforeProtocolList** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <ObjCSpaceBeforeProtocolList>`
- Add a space in front of an Objective-C protocol list, i.e. use
- ``Foo <Protocol>`` instead of ``Foo<Protocol>``.
+: Add a space in front of an Objective-C protocol list, i.e. use
+ `Foo <Protocol>` instead of `Foo<Protocol>`.
-.. _OneLineFormatOffRegex:
+(onelineformatoffregex)=
-**OneLineFormatOffRegex** (``String``) :versionbadge:`clang-format 21` :ref:`¶ <OneLineFormatOffRegex>`
- A regular expression that describes markers for turning formatting off for
+**OneLineFormatOffRegex** (`String`) {versionbadge}`clang-format 21` {ref}`¶ <OneLineFormatOffRegex>`
+
+: A regular expression that describes markers for turning formatting off for
one line. If it matches a comment that is the only token of a line,
clang-format skips the comment and the next line. Otherwise, clang-format
skips lines containing a matched token.
- .. note::
-
- This option does not apply to ``IntegerLiteralSeparator`` and
- ``NumericLiteralCase``.
-
- .. code-block:: c++
-
- // OneLineFormatOffRegex: ^(// NOLINT|logger$)
- // results in the output below:
- int a;
- int b ; // NOLINT
- int c;
- // NOLINTNEXTLINE
- int d ;
- int e;
- s = "// NOLINT";
- logger() ;
- logger2();
- my_logger();
-
-.. _PPIndentWidth:
-
-**PPIndentWidth** (``Integer``) :versionbadge:`clang-format 13` :ref:`¶ <PPIndentWidth>`
- The number of columns to use for indentation of preprocessor statements.
- When set to -1 (default) ``IndentWidth`` is used also for preprocessor
+ :::{note}
+ This option does not apply to `IntegerLiteralSeparator` and
+ `NumericLiteralCase`.
+ :::
+
+ ```c++
+ // OneLineFormatOffRegex: ^(// NOLINT|logger$)
+ // results in the output below:
+ int a;
+ int b ; // NOLINT
+ int c;
+ // NOLINTNEXTLINE
+ int d ;
+ int e;
+ s = "// NOLINT";
+ logger() ;
+ logger2();
+ my_logger();
+ ```
+
+(ppindentwidth)=
+
+**PPIndentWidth** (`Integer`) {versionbadge}`clang-format 13` {ref}`¶ <PPIndentWidth>`
+
+: The number of columns to use for indentation of preprocessor statements.
+ When set to -1 (default) `IndentWidth` is used also for preprocessor
statements.
- .. code-block:: c++
+ ```c++
+ PPIndentWidth: 1
- PPIndentWidth: 1
+ #ifdef __linux__
+ # define FOO
+ #else
+ # define BAR
+ #endif
+ ```
- #ifdef __linux__
- # define FOO
- #else
- # define BAR
- #endif
+(packarguments)=
-.. _PackArguments:
+**PackArguments** (`PackArgumentsStyle`) {versionbadge}`clang-format 23` {ref}`¶ <PackArguments>`
-**PackArguments** (``PackArgumentsStyle``) :versionbadge:`clang-format 23` :ref:`¶ <PackArguments>`
- Options related to packing arguments of function calls.
+: Options related to packing arguments of function calls.
Nested configuration flags:
Options related to packing arguments of function calls.
- * ``BinPackArgumentsStyle BinPack`` :versionbadge:`clang-format 3.7`
+ - `BinPackArgumentsStyle BinPack` {versionbadge}`clang-format 3.7`
The bin pack arguments style to use.
Possible values:
- * ``BPAS_BinPack`` (in configuration: ``BinPack``)
+ - `BPAS_BinPack` (in configuration: `BinPack`)
Bin-pack arguments.
- .. code-block:: c++
-
- void f() {
- f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa,
- aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
- }
+ ```c++
+ void f() {
+ f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa,
+ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
+ }
+ ```
- * ``BPAS_OnePerLine`` (in configuration: ``OnePerLine``)
+ - `BPAS_OnePerLine` (in configuration: `OnePerLine`)
Put all arguments on the current line if they fit.
Otherwise, put each one on its own line.
- .. code-block:: c++
-
- void f() {
- f(aaaaaaaaaaaaaaaaaaaa,
- aaaaaaaaaaaaaaaaaaaa,
- aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
- }
+ ```c++
+ void f() {
+ f(aaaaaaaaaaaaaaaaaaaa,
+ aaaaaaaaaaaaaaaaaaaa,
+ aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
+ }
+ ```
- * ``BPAS_UseBreakAfter`` (in configuration: ``UseBreakAfter``)
- Use the ``BreakAfter`` option to handle argument packing instead.
- If the ``BreakAfter`` limit is not exceeded, behave like ``BinPack``.
+ - `BPAS_UseBreakAfter` (in configuration: `UseBreakAfter`)
+ Use the `BreakAfter` option to handle argument packing instead.
+ If the `BreakAfter` limit is not exceeded, behave like `BinPack`.
- * ``unsigned BreakAfter`` :versionbadge:`clang-format 23` An argument list with more arguments than the specified number will be
+ - `unsigned BreakAfter` {versionbadge}`clang-format 23` An argument list with more arguments than the specified number will be
formatted with one argument per line. This option must be used with
- ``BinPack: UseBreakAfter``.
+ `BinPack: UseBreakAfter`.
- .. code-block:: c++
+ ```c++
+ PackArguments:
+ BinPack: UseBreakAfter
+ BreakAfter: 3
- PackArguments:
- BinPack: UseBreakAfter
- BreakAfter: 3
+ void f() {
+ foo(1);
- void f() {
- foo(1);
+ bar(1, 2, 3);
- bar(1, 2, 3);
+ baz(1,
+ 2,
+ 3,
+ 4);
+ }
+ ```
- baz(1,
- 2,
- 3,
- 4);
- }
+(packconstructorinitializers)=
-.. _PackConstructorInitializers:
+**PackConstructorInitializers** (`PackConstructorInitializersStyle`) {versionbadge}`clang-format 14` {ref}`¶ <PackConstructorInitializers>`
-**PackConstructorInitializers** (``PackConstructorInitializersStyle``) :versionbadge:`clang-format 14` :ref:`¶ <PackConstructorInitializers>`
- The pack constructor initializers style to use.
+: The pack constructor initializers style to use.
Possible values:
- * ``PCIS_Never`` (in configuration: ``Never``)
+ - `PCIS_Never` (in configuration: `Never`)
Always put each constructor initializer on its own line.
- .. code-block:: c++
-
- Constructor()
- : a(),
- b()
+ ```c++
+ Constructor()
+ : a(),
+ b()
+ ```
- * ``PCIS_BinPack`` (in configuration: ``BinPack``)
+ - `PCIS_BinPack` (in configuration: `BinPack`)
Bin-pack constructor initializers.
- .. code-block:: c++
+ ```c++
+ Constructor()
+ : aaaaaaaaaaaaaaaaaaaa(), bbbbbbbbbbbbbbbbbbbb(),
+ cccccccccccccccccccc()
+ ```
- Constructor()
- : aaaaaaaaaaaaaaaaaaaa(), bbbbbbbbbbbbbbbbbbbb(),
- cccccccccccccccccccc()
-
- * ``PCIS_CurrentLine`` (in configuration: ``CurrentLine``)
+ - `PCIS_CurrentLine` (in configuration: `CurrentLine`)
Put all constructor initializers on the current line if they fit.
Otherwise, put each one on its own line.
- .. code-block:: c++
-
- Constructor() : a(), b()
+ ```c++
+ Constructor() : a(), b()
- Constructor()
- : aaaaaaaaaaaaaaaaaaaa(),
- bbbbbbbbbbbbbbbbbbbb(),
- ddddddddddddd()
+ Constructor()
+ : aaaaaaaaaaaaaaaaaaaa(),
+ bbbbbbbbbbbbbbbbbbbb(),
+ ddddddddddddd()
+ ```
- * ``PCIS_NextLine`` (in configuration: ``NextLine``)
- Same as ``PCIS_CurrentLine`` except that if all constructor initializers
+ - `PCIS_NextLine` (in configuration: `NextLine`)
+ Same as `PCIS_CurrentLine` except that if all constructor initializers
do not fit on the current line, try to fit them on the next line.
- .. code-block:: c++
+ ```c++
+ Constructor() : a(), b()
- Constructor() : a(), b()
+ Constructor()
+ : aaaaaaaaaaaaaaaaaaaa(), bbbbbbbbbbbbbbbbbbbb(), ddddddddddddd()
- Constructor()
- : aaaaaaaaaaaaaaaaaaaa(), bbbbbbbbbbbbbbbbbbbb(), ddddddddddddd()
+ Constructor()
+ : aaaaaaaaaaaaaaaaaaaa(),
+ bbbbbbbbbbbbbbbbbbbb(),
+ cccccccccccccccccccc()
+ ```
- Constructor()
- : aaaaaaaaaaaaaaaaaaaa(),
- bbbbbbbbbbbbbbbbbbbb(),
- cccccccccccccccccccc()
-
- * ``PCIS_NextLineOnly`` (in configuration: ``NextLineOnly``)
+ - `PCIS_NextLineOnly` (in configuration: `NextLineOnly`)
Put all constructor initializers on the next line if they fit.
Otherwise, put each one on its own line.
- .. code-block:: c++
+ ```c++
+ Constructor()
+ : a(), b()
- Constructor()
- : a(), b()
+ Constructor()
+ : aaaaaaaaaaaaaaaaaaaa(), bbbbbbbbbbbbbbbbbbbb(), ddddddddddddd()
- Constructor()
- : aaaaaaaaaaaaaaaaaaaa(), bbbbbbbbbbbbbbbbbbbb(), ddddddddddddd()
+ Constructor()
+ : aaaaaaaaaaaaaaaaaaaa(),
+ bbbbbbbbbbbbbbbbbbbb(),
+ cccccccccccccccccccc()
+ ```
- Constructor()
- : aaaaaaaaaaaaaaaaaaaa(),
- bbbbbbbbbbbbbbbbbbbb(),
- cccccccccccccccccccc()
+(packparameters)=
-.. _PackParameters:
+**PackParameters** (`PackParametersStyle`) {versionbadge}`clang-format 23` {ref}`¶ <PackParameters>`
-**PackParameters** (``PackParametersStyle``) :versionbadge:`clang-format 23` :ref:`¶ <PackParameters>`
- Options related to packing parameters of function declarations and
+: Options related to packing parameters of function declarations and
definitions.
Nested configuration flags:
@@ -6050,255 +6158,268 @@ the configuration (without a prefix: ``Auto``).
Options related to packing parameters of function declarations and
definitions.
- * ``BinPackParametersStyle BinPack`` :versionbadge:`clang-format 3.7`
+ - `BinPackParametersStyle BinPack` {versionbadge}`clang-format 3.7`
The bin pack parameters style to use.
Possible values:
- * ``BPPS_BinPack`` (in configuration: ``BinPack``)
+ - `BPPS_BinPack` (in configuration: `BinPack`)
Bin-pack parameters.
- .. code-block:: c++
+ ```c++
+ void f(int a, int bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb,
+ int ccccccccccccccccccccccccccccccccccccccccccc);
+ ```
- void f(int a, int bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb,
- int ccccccccccccccccccccccccccccccccccccccccccc);
-
- * ``BPPS_OnePerLine`` (in configuration: ``OnePerLine``)
+ - `BPPS_OnePerLine` (in configuration: `OnePerLine`)
Put all parameters on the current line if they fit.
Otherwise, put each one on its own line.
- .. code-block:: c++
-
- void f(int a, int b, int c);
+ ```c++
+ void f(int a, int b, int c);
- void f(int a,
- int b,
- int ccccccccccccccccccccccccccccccccccccc);
+ void f(int a,
+ int b,
+ int ccccccccccccccccccccccccccccccccccccc);
+ ```
- * ``BPPS_AlwaysOnePerLine`` (in configuration: ``AlwaysOnePerLine``)
+ - `BPPS_AlwaysOnePerLine` (in configuration: `AlwaysOnePerLine`)
Always put each parameter on its own line.
- .. code-block:: c++
+ ```c++
+ void f(int a,
+ int b,
+ int c);
+ ```
- void f(int a,
- int b,
- int c);
+ - `BPPS_UseBreakAfter` (in configuration: `UseBreakAfter`)
+ Use the `BreakAfter` option to handle parameter packing instead.
+ If the `BreakAfter` limit is not exceeded, behave like `BinPack`.
- * ``BPPS_UseBreakAfter`` (in configuration: ``UseBreakAfter``)
- Use the ``BreakAfter`` option to handle parameter packing instead.
- If the ``BreakAfter`` limit is not exceeded, behave like ``BinPack``.
-
- * ``unsigned BreakAfter`` :versionbadge:`clang-format 23` A parameter list with more parameters than the specified number will be
+ - `unsigned BreakAfter` {versionbadge}`clang-format 23` A parameter list with more parameters than the specified number will be
formatted with one parameter per line. This option must be used with
- ``BinPack: UseBreakAfter``.
+ `BinPack: UseBreakAfter`.
- .. code-block:: c++
+ ```c++
+ PackParameters:
+ BinPack: UseBreakAfter
+ BreakAfter: 3
- PackParameters:
- BinPack: UseBreakAfter
- BreakAfter: 3
+ void foo(int a);
- void foo(int a);
+ void bar(int a, int b, int c);
- void bar(int a, int b, int c);
+ void baz(int a,
+ int b,
+ int c,
+ int d);
+ ```
- void baz(int a,
- int b,
- int c,
- int d);
+(penaltybreakassignment)=
-.. _PenaltyBreakAssignment:
+**PenaltyBreakAssignment** (`Unsigned`) {versionbadge}`clang-format 5` {ref}`¶ <PenaltyBreakAssignment>`
-**PenaltyBreakAssignment** (``Unsigned``) :versionbadge:`clang-format 5` :ref:`¶ <PenaltyBreakAssignment>`
- The penalty for breaking around an assignment operator.
+: The penalty for breaking around an assignment operator.
-.. _PenaltyBreakBeforeFirstCallParameter:
+(penaltybreakbeforefirstcallparameter)=
-**PenaltyBreakBeforeFirstCallParameter** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <PenaltyBreakBeforeFirstCallParameter>`
- The penalty for breaking a function call after ``call(``.
+**PenaltyBreakBeforeFirstCallParameter** (`Unsigned`) {versionbadge}`clang-format 3.7` {ref}`¶ <PenaltyBreakBeforeFirstCallParameter>`
-.. _PenaltyBreakBeforeMemberAccess:
+: The penalty for breaking a function call after `call(`.
-**PenaltyBreakBeforeMemberAccess** (``Unsigned``) :versionbadge:`clang-format 20` :ref:`¶ <PenaltyBreakBeforeMemberAccess>`
- The penalty for breaking before a member access operator (``.``, ``->``).
+(penaltybreakbeforememberaccess)=
-.. _PenaltyBreakComment:
+**PenaltyBreakBeforeMemberAccess** (`Unsigned`) {versionbadge}`clang-format 20` {ref}`¶ <PenaltyBreakBeforeMemberAccess>`
-**PenaltyBreakComment** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <PenaltyBreakComment>`
- The penalty for each line break introduced inside a comment.
+: The penalty for breaking before a member access operator (`.`, `->`).
-.. _PenaltyBreakFirstLessLess:
+(penaltybreakcomment)=
-**PenaltyBreakFirstLessLess** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <PenaltyBreakFirstLessLess>`
- The penalty for breaking before the first ``<<``.
+**PenaltyBreakComment** (`Unsigned`) {versionbadge}`clang-format 3.7` {ref}`¶ <PenaltyBreakComment>`
-.. _PenaltyBreakOpenParenthesis:
+: The penalty for each line break introduced inside a comment.
-**PenaltyBreakOpenParenthesis** (``Unsigned``) :versionbadge:`clang-format 14` :ref:`¶ <PenaltyBreakOpenParenthesis>`
- The penalty for breaking after ``(``.
+(penaltybreakfirstlessless)=
-.. _PenaltyBreakScopeResolution:
+**PenaltyBreakFirstLessLess** (`Unsigned`) {versionbadge}`clang-format 3.7` {ref}`¶ <PenaltyBreakFirstLessLess>`
-**PenaltyBreakScopeResolution** (``Unsigned``) :versionbadge:`clang-format 18` :ref:`¶ <PenaltyBreakScopeResolution>`
- The penalty for breaking after ``::``.
+: The penalty for breaking before the first `<<`.
-.. _PenaltyBreakString:
+(penaltybreakopenparenthesis)=
-**PenaltyBreakString** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <PenaltyBreakString>`
- The penalty for each line break introduced inside a string literal.
+**PenaltyBreakOpenParenthesis** (`Unsigned`) {versionbadge}`clang-format 14` {ref}`¶ <PenaltyBreakOpenParenthesis>`
-.. _PenaltyBreakTemplateDeclaration:
+: The penalty for breaking after `(`.
-**PenaltyBreakTemplateDeclaration** (``Unsigned``) :versionbadge:`clang-format 7` :ref:`¶ <PenaltyBreakTemplateDeclaration>`
- The penalty for breaking after template declaration.
+(penaltybreakscoperesolution)=
-.. _PenaltyExcessCharacter:
+**PenaltyBreakScopeResolution** (`Unsigned`) {versionbadge}`clang-format 18` {ref}`¶ <PenaltyBreakScopeResolution>`
-**PenaltyExcessCharacter** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <PenaltyExcessCharacter>`
- The penalty for each character outside of the column limit.
+: The penalty for breaking after `::`.
-.. _PenaltyIndentedWhitespace:
+(penaltybreakstring)=
-**PenaltyIndentedWhitespace** (``Unsigned``) :versionbadge:`clang-format 12` :ref:`¶ <PenaltyIndentedWhitespace>`
- Penalty for each character of whitespace indentation
- (counted relative to leading non-whitespace column).
+**PenaltyBreakString** (`Unsigned`) {versionbadge}`clang-format 3.7` {ref}`¶ <PenaltyBreakString>`
-.. _PenaltyReturnTypeOnItsOwnLine:
+: The penalty for each line break introduced inside a string literal.
-**PenaltyReturnTypeOnItsOwnLine** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <PenaltyReturnTypeOnItsOwnLine>`
- Penalty for putting the return type of a function onto its own line.
+(penaltybreaktemplatedeclaration)=
-.. _PointerAlignment:
+**PenaltyBreakTemplateDeclaration** (`Unsigned`) {versionbadge}`clang-format 7` {ref}`¶ <PenaltyBreakTemplateDeclaration>`
-**PointerAlignment** (``PointerAlignmentStyle``) :versionbadge:`clang-format 3.7` :ref:`¶ <PointerAlignment>`
- Pointer and reference alignment style.
+: The penalty for breaking after template declaration.
- Possible values:
+(penaltyexcesscharacter)=
- * ``PAS_Left`` (in configuration: ``Left``)
- Align pointer to the left.
+**PenaltyExcessCharacter** (`Unsigned`) {versionbadge}`clang-format 3.7` {ref}`¶ <PenaltyExcessCharacter>`
- .. code-block:: c++
+: The penalty for each character outside of the column limit.
- int* a;
+(penaltyindentedwhitespace)=
- * ``PAS_Right`` (in configuration: ``Right``)
- Align pointer to the right.
+**PenaltyIndentedWhitespace** (`Unsigned`) {versionbadge}`clang-format 12` {ref}`¶ <PenaltyIndentedWhitespace>`
- .. code-block:: c++
+: Penalty for each character of whitespace indentation
+ (counted relative to leading non-whitespace column).
- int *a;
+(penaltyreturntypeonitsownline)=
- * ``PAS_Middle`` (in configuration: ``Middle``)
- Align pointer in the middle.
+**PenaltyReturnTypeOnItsOwnLine** (`Unsigned`) {versionbadge}`clang-format 3.7` {ref}`¶ <PenaltyReturnTypeOnItsOwnLine>`
- .. code-block:: c++
+: Penalty for putting the return type of a function onto its own line.
- int * a;
+(pointeralignment)=
+**PointerAlignment** (`PointerAlignmentStyle`) {versionbadge}`clang-format 3.7` {ref}`¶ <PointerAlignment>`
+: Pointer and reference alignment style.
-.. _QualifierAlignment:
+ Possible values:
-**QualifierAlignment** (``QualifierAlignmentStyle``) :versionbadge:`clang-format 14` :ref:`¶ <QualifierAlignment>`
- Different ways to arrange specifiers and qualifiers (e.g. const/volatile).
+ - `PAS_Left` (in configuration: `Left`)
+ Align pointer to the left.
- .. warning::
+ ```c++
+ int* a;
+ ```
- Setting ``QualifierAlignment`` to something other than ``Leave``, COULD
- lead to incorrect code formatting due to incorrect decisions made due to
- clang-formats lack of complete semantic information.
- As such extra care should be taken to review code changes made by the use
- of this option.
+ - `PAS_Right` (in configuration: `Right`)
+ Align pointer to the right.
- Possible values:
+ ```c++
+ int *a;
+ ```
- * ``QAS_Leave`` (in configuration: ``Leave``)
- Don't change specifiers/qualifiers to either Left or Right alignment
- (default).
+ - `PAS_Middle` (in configuration: `Middle`)
+ Align pointer in the middle.
- .. code-block:: c++
+ ```c++
+ int * a;
+ ```
- int const a;
- const int *a;
- * ``QAS_Left`` (in configuration: ``Left``)
- Change specifiers/qualifiers to be left-aligned.
- .. code-block:: c++
+(qualifieralignment)=
- const int a;
- const int *a;
+**QualifierAlignment** (`QualifierAlignmentStyle`) {versionbadge}`clang-format 14` {ref}`¶ <QualifierAlignment>`
- * ``QAS_Right`` (in configuration: ``Right``)
- Change specifiers/qualifiers to be right-aligned.
+: Different ways to arrange specifiers and qualifiers (e.g. const/volatile).
- .. code-block:: c++
+ :::{warning}
+ Setting `QualifierAlignment` to something other than `Leave`, COULD
+ lead to incorrect code formatting due to incorrect decisions made due to
+ clang-formats lack of complete semantic information.
+ As such extra care should be taken to review code changes made by the use
+ of this option.
+ :::
- int const a;
- int const *a;
+ Possible values:
- * ``QAS_Custom`` (in configuration: ``Custom``)
- Change specifiers/qualifiers to be aligned based on ``QualifierOrder``.
- With:
+ - `QAS_Leave` (in configuration: `Leave`)
+ Don't change specifiers/qualifiers to either Left or Right alignment
+ (default).
- .. code-block:: yaml
+ ```c++
+ int const a;
+ const int *a;
+ ```
- QualifierOrder: [inline, static, type, const]
+ - `QAS_Left` (in configuration: `Left`)
+ Change specifiers/qualifiers to be left-aligned.
+ ```c++
+ const int a;
+ const int *a;
+ ```
- .. code-block:: c++
+ - `QAS_Right` (in configuration: `Right`)
+ Change specifiers/qualifiers to be right-aligned.
+ ```c++
+ int const a;
+ int const *a;
+ ```
- int const a;
- int const *a;
+ - `QAS_Custom` (in configuration: `Custom`)
+ Change specifiers/qualifiers to be aligned based on `QualifierOrder`.
+ With:
+ ```yaml
+ QualifierOrder: [inline, static, type, const]
+ ```
+ ```c++
-.. _QualifierOrder:
+ int const a;
+ int const *a;
+ ```
-**QualifierOrder** (``List of Strings``) :versionbadge:`clang-format 14` :ref:`¶ <QualifierOrder>`
- The order in which the qualifiers appear.
- The order is an array that can contain any of the following:
- * ``const``
- * ``inline``
- * ``static``
- * ``friend``
- * ``constexpr``
- * ``volatile``
- * ``restrict``
- * ``type``
+(qualifierorder)=
- .. note::
+**QualifierOrder** (`List of Strings`) {versionbadge}`clang-format 14` {ref}`¶ <QualifierOrder>`
- It must contain ``type``.
+: The order in which the qualifiers appear.
+ The order is an array that can contain any of the following:
- Items to the left of ``type`` will be placed to the left of the type and
- aligned in the order supplied. Items to the right of ``type`` will be
+ - `const`
+ - `inline`
+ - `static`
+ - `friend`
+ - `constexpr`
+ - `volatile`
+ - `restrict`
+ - `type`
+
+ :::{note}
+ It must contain `type`.
+ :::
+
+ Items to the left of `type` will be placed to the left of the type and
+ aligned in the order supplied. Items to the right of `type` will be
placed to the right of the type and aligned in the order supplied.
+ ```yaml
+ QualifierOrder: [inline, static, type, const, volatile]
+ ```
- .. code-block:: yaml
-
- QualifierOrder: [inline, static, type, const, volatile]
+(rawstringformats)=
-.. _RawStringFormats:
+**RawStringFormats** (`List of RawStringFormats`) {versionbadge}`clang-format 6` {ref}`¶ <RawStringFormats>`
-**RawStringFormats** (``List of RawStringFormats``) :versionbadge:`clang-format 6` :ref:`¶ <RawStringFormats>`
- Defines hints for detecting supported languages code blocks in raw
+: Defines hints for detecting supported languages code blocks in raw
strings.
A raw string with a matching delimiter or a matching enclosing function
name will be reformatted assuming the specified language based on the
style for that language defined in the .clang-format file. If no style has
been defined in the .clang-format file for the specific language, a
- predefined style given by ``BasedOnStyle`` is used. If ``BasedOnStyle`` is
- not found, the formatting is based on ``LLVM`` style. A matching delimiter
+ predefined style given by `BasedOnStyle` is used. If `BasedOnStyle` is
+ not found, the formatting is based on `LLVM` style. A matching delimiter
takes precedence over a matching enclosing function name for determining
the language of the raw string contents.
@@ -6310,1395 +6431,1444 @@ the configuration (without a prefix: ``Auto``).
To configure this in the .clang-format file, use:
- .. code-block:: yaml
-
- RawStringFormats:
- - Language: TextProto
- Delimiters:
- - pb
- - proto
- EnclosingFunctions:
- - PARSE_TEXT_PROTO
- BasedOnStyle: google
- - Language: Cpp
- Delimiters:
- - cc
- - cpp
- BasedOnStyle: LLVM
- CanonicalDelimiter: cc
-
-.. _ReferenceAlignment:
-
-**ReferenceAlignment** (``ReferenceAlignmentStyle``) :versionbadge:`clang-format 13` :ref:`¶ <ReferenceAlignment>`
- Reference alignment style (overrides ``PointerAlignment`` for references).
+ ```yaml
+ RawStringFormats:
+ - Language: TextProto
+ Delimiters:
+ - pb
+ - proto
+ EnclosingFunctions:
+ - PARSE_TEXT_PROTO
+ BasedOnStyle: google
+ - Language: Cpp
+ Delimiters:
+ - cc
+ - cpp
+ BasedOnStyle: LLVM
+ CanonicalDelimiter: cc
+ ```
+
+(referencealignment)=
+
+**ReferenceAlignment** (`ReferenceAlignmentStyle`) {versionbadge}`clang-format 13` {ref}`¶ <ReferenceAlignment>`
+
+: Reference alignment style (overrides `PointerAlignment` for references).
Possible values:
- * ``RAS_Pointer`` (in configuration: ``Pointer``)
- Align reference like ``PointerAlignment``.
+ - `RAS_Pointer` (in configuration: `Pointer`)
+ Align reference like `PointerAlignment`.
- * ``RAS_Left`` (in configuration: ``Left``)
+ - `RAS_Left` (in configuration: `Left`)
Align reference to the left.
- .. code-block:: c++
-
- int& a;
+ ```c++
+ int& a;
+ ```
- * ``RAS_Right`` (in configuration: ``Right``)
+ - `RAS_Right` (in configuration: `Right`)
Align reference to the right.
- .. code-block:: c++
+ ```c++
+ int &a;
+ ```
- int &a;
-
- * ``RAS_Middle`` (in configuration: ``Middle``)
+ - `RAS_Middle` (in configuration: `Middle`)
Align reference in the middle.
- .. code-block:: c++
+ ```c++
+ int & a;
+ ```
- int & a;
+(reflowcomments)=
-.. _ReflowComments:
+**ReflowComments** (`ReflowCommentsStyle`) {versionbadge}`clang-format 3.8` {ref}`¶ <ReflowComments>`
-**ReflowComments** (``ReflowCommentsStyle``) :versionbadge:`clang-format 3.8` :ref:`¶ <ReflowComments>`
- Comment reformatting style.
+: Comment reformatting style.
Possible values:
- * ``RCS_Never`` (in configuration: ``Never``)
+ - `RCS_Never` (in configuration: `Never`)
Leave comments untouched.
- .. code-block:: c++
-
- // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
- /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
- /* third veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
- * and a misaligned second line */
+ ```c++
+ // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
+ /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
+ /* third veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
+ - and a misaligned second line */
+ ```
- * ``RCS_IndentOnly`` (in configuration: ``IndentOnly``)
+ - `RCS_IndentOnly` (in configuration: `IndentOnly`)
Only apply indentation rules, moving comments left or right, without
changing formatting inside the comments.
- .. code-block:: c++
+ ```c++
+ // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
+ /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
+ /* third veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
+ - and a misaligned second line */
+ ```
- // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
- /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
- /* third veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
- * and a misaligned second line */
-
- * ``RCS_Always`` (in configuration: ``Always``)
+ - `RCS_Always` (in configuration: `Always`)
Apply indentation rules and reflow long comments into new lines, trying
- to obey the ``ColumnLimit``.
-
- .. code-block:: c++
+ to obey the `ColumnLimit`.
- // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
- // information
- /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
- * information */
- /* third veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
- * information and a misaligned second line */
+ ```c++
+ // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
+ // information
+ /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
+ - information */
+ /* third veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
+ - information and a misaligned second line */
+ ```
-.. _RemoveBracesLLVM:
+(removebracesllvm)=
-**RemoveBracesLLVM** (``Boolean``) :versionbadge:`clang-format 14` :ref:`¶ <RemoveBracesLLVM>`
- Remove optional braces of control statements (``if``, ``else``, ``for``,
- and ``while``) in C++ according to the LLVM coding style.
+**RemoveBracesLLVM** (`Boolean`) {versionbadge}`clang-format 14` {ref}`¶ <RemoveBracesLLVM>`
- .. warning::
+: Remove optional braces of control statements (`if`, `else`, `for`,
+ and `while`) in C++ according to the LLVM coding style.
- This option will be renamed and expanded to support other styles.
+ :::{warning}
+ This option will be renamed and expanded to support other styles.
+ :::
- .. warning::
+ :::{warning}
+ Setting this option to `true` could lead to incorrect code formatting
+ due to clang-format's lack of complete semantic information. As such,
+ extra care should be taken to review code changes made by this option.
+ :::
- Setting this option to ``true`` could lead to incorrect code formatting
- due to clang-format's lack of complete semantic information. As such,
- extra care should be taken to review code changes made by this option.
-
- .. code-block:: c++
-
- false: true:
-
- if (isa<FunctionDecl>(D)) { vs. if (isa<FunctionDecl>(D))
- handleFunctionDecl(D); handleFunctionDecl(D);
- } else if (isa<VarDecl>(D)) { else if (isa<VarDecl>(D))
- handleVarDecl(D); handleVarDecl(D);
- }
+ ```c++
+ false: true:
- if (isa<VarDecl>(D)) { vs. if (isa<VarDecl>(D)) {
- for (auto *A : D.attrs()) { for (auto *A : D.attrs())
- if (shouldProcessAttr(A)) { if (shouldProcessAttr(A))
- handleAttr(A); handleAttr(A);
- } }
- }
- }
+ if (isa<FunctionDecl>(D)) { vs. if (isa<FunctionDecl>(D))
+ handleFunctionDecl(D); handleFunctionDecl(D);
+ } else if (isa<VarDecl>(D)) { else if (isa<VarDecl>(D))
+ handleVarDecl(D); handleVarDecl(D);
+ }
- if (isa<FunctionDecl>(D)) { vs. if (isa<FunctionDecl>(D))
- for (auto *A : D.attrs()) { for (auto *A : D.attrs())
+ if (isa<VarDecl>(D)) { vs. if (isa<VarDecl>(D)) {
+ for (auto *A : D.attrs()) { for (auto *A : D.attrs())
+ if (shouldProcessAttr(A)) { if (shouldProcessAttr(A))
handleAttr(A); handleAttr(A);
- }
+ } }
}
+ }
- if (auto *D = (T)(D)) { vs. if (auto *D = (T)(D)) {
- if (shouldProcess(D)) { if (shouldProcess(D))
- handleVarDecl(D); handleVarDecl(D);
- } else { else
- markAsIgnored(D); markAsIgnored(D);
- } }
+ if (isa<FunctionDecl>(D)) { vs. if (isa<FunctionDecl>(D))
+ for (auto *A : D.attrs()) { for (auto *A : D.attrs())
+ handleAttr(A); handleAttr(A);
}
+ }
- if (a) { vs. if (a)
- b(); b();
- } else { else if (c)
- if (c) { d();
- d(); else
- } else { e();
- e();
- }
+ if (auto *D = (T)(D)) { vs. if (auto *D = (T)(D)) {
+ if (shouldProcess(D)) { if (shouldProcess(D))
+ handleVarDecl(D); handleVarDecl(D);
+ } else { else
+ markAsIgnored(D); markAsIgnored(D);
+ } }
+ }
+
+ if (a) { vs. if (a)
+ b(); b();
+ } else { else if (c)
+ if (c) { d();
+ d(); else
+ } else { e();
+ e();
}
+ }
+ ```
-.. _RemoveEmptyLinesInUnwrappedLines:
+(removeemptylinesinunwrappedlines)=
-**RemoveEmptyLinesInUnwrappedLines** (``Boolean``) :versionbadge:`clang-format 20` :ref:`¶ <RemoveEmptyLinesInUnwrappedLines>`
- Remove empty lines within unwrapped lines.
+**RemoveEmptyLinesInUnwrappedLines** (`Boolean`) {versionbadge}`clang-format 20` {ref}`¶ <RemoveEmptyLinesInUnwrappedLines>`
- .. code-block:: c++
+: Remove empty lines within unwrapped lines.
- false: true:
+ ```c++
+ false: true:
- int c vs. int c = a + b;
+ int c vs. int c = a + b;
- = a + b;
+ = a + b;
- enum : unsigned vs. enum : unsigned {
- AA = 0,
- { BB
- AA = 0, } myEnum;
- BB
- } myEnum;
+ enum : unsigned vs. enum : unsigned {
+ AA = 0,
+ { BB
+ AA = 0, } myEnum;
+ BB
+ } myEnum;
- while ( vs. while (true) {
- }
- true) {
- }
+ while ( vs. while (true) {
+ }
+ true) {
+ }
+ ```
-.. _RemoveParentheses:
+(removeparentheses)=
-**RemoveParentheses** (``RemoveParenthesesStyle``) :versionbadge:`clang-format 17` :ref:`¶ <RemoveParentheses>`
- Remove redundant parentheses.
+**RemoveParentheses** (`RemoveParenthesesStyle`) {versionbadge}`clang-format 17` {ref}`¶ <RemoveParentheses>`
- .. warning::
+: Remove redundant parentheses.
- Setting this option to any value other than ``Leave`` could lead to
- incorrect code formatting due to clang-format's lack of complete semantic
- information. As such, extra care should be taken to review code changes
- made by this option.
+ :::{warning}
+ Setting this option to any value other than `Leave` could lead to
+ incorrect code formatting due to clang-format's lack of complete semantic
+ information. As such, extra care should be taken to review code changes
+ made by this option.
+ :::
Possible values:
- * ``RPS_Leave`` (in configuration: ``Leave``)
+ - `RPS_Leave` (in configuration: `Leave`)
Do not remove parentheses.
- .. code-block:: c++
+ ```c++
+ class __declspec((dllimport)) X {};
+ co_return (((0)));
+ return ((a + b) - ((c + d)));
+ ```
- class __declspec((dllimport)) X {};
- co_return (((0)));
- return ((a + b) - ((c + d)));
-
- * ``RPS_MultipleParentheses`` (in configuration: ``MultipleParentheses``)
+ - `RPS_MultipleParentheses` (in configuration: `MultipleParentheses`)
Replace multiple parentheses with single parentheses.
- .. code-block:: c++
-
- class __declspec(dllimport) X {};
- co_return (0);
- return ((a + b) - (c + d));
+ ```c++
+ class __declspec(dllimport) X {};
+ co_return (0);
+ return ((a + b) - (c + d));
+ ```
- * ``RPS_ReturnStatement`` (in configuration: ``ReturnStatement``)
+ - `RPS_ReturnStatement` (in configuration: `ReturnStatement`)
Also remove parentheses enclosing the expression in a
- ``return``/``co_return`` statement.
+ `return`/`co_return` statement.
- .. code-block:: c++
+ ```c++
+ class __declspec(dllimport) X {};
+ co_return 0;
+ return (a + b) - (c + d);
+ ```
- class __declspec(dllimport) X {};
- co_return 0;
- return (a + b) - (c + d);
+(removesemicolon)=
-.. _RemoveSemicolon:
+**RemoveSemicolon** (`Boolean`) {versionbadge}`clang-format 16` {ref}`¶ <RemoveSemicolon>`
-**RemoveSemicolon** (``Boolean``) :versionbadge:`clang-format 16` :ref:`¶ <RemoveSemicolon>`
- Remove semicolons after the closing braces of functions and
+: Remove semicolons after the closing braces of functions and
constructors/destructors.
- .. warning::
+ :::{warning}
+ Setting this option to `true` could lead to incorrect code formatting
+ due to clang-format's lack of complete semantic information. As such,
+ extra care should be taken to review code changes made by this option.
+ :::
- Setting this option to ``true`` could lead to incorrect code formatting
- due to clang-format's lack of complete semantic information. As such,
- extra care should be taken to review code changes made by this option.
+ ```c++
+ false: true:
- .. code-block:: c++
+ int max(int a, int b) { int max(int a, int b) {
+ return a > b ? a : b; return a > b ? a : b;
+ }; }
- false: true:
+ ```
- int max(int a, int b) { int max(int a, int b) {
- return a > b ? a : b; return a > b ? a : b;
- }; }
+(requiresclauseposition)=
-.. _RequiresClausePosition:
+**RequiresClausePosition** (`RequiresClausePositionStyle`) {versionbadge}`clang-format 15` {ref}`¶ <RequiresClausePosition>`
-**RequiresClausePosition** (``RequiresClausePositionStyle``) :versionbadge:`clang-format 15` :ref:`¶ <RequiresClausePosition>`
- The position of the ``requires`` clause.
+: The position of the `requires` clause.
Possible values:
- * ``RCPS_OwnLine`` (in configuration: ``OwnLine``)
- Always put the ``requires`` clause on its own line (possibly followed by
+ - `RCPS_OwnLine` (in configuration: `OwnLine`)
+ Always put the `requires` clause on its own line (possibly followed by
a semicolon).
- .. code-block:: c++
-
- template <typename T>
- requires C<T>
- struct Foo {...
+ ```c++
+ template <typename T>
+ requires C<T>
+ struct Foo {...
- template <typename T>
- void bar(T t)
- requires C<T>;
+ template <typename T>
+ void bar(T t)
+ requires C<T>;
- template <typename T>
- requires C<T>
- void bar(T t) {...
+ template <typename T>
+ requires C<T>
+ void bar(T t) {...
- template <typename T>
- void baz(T t)
- requires C<T>
- {...
+ template <typename T>
+ void baz(T t)
+ requires C<T>
+ {...
+ ```
- * ``RCPS_OwnLineWithBrace`` (in configuration: ``OwnLineWithBrace``)
- As with ``OwnLine``, except, unless otherwise prohibited, place a
+ - `RCPS_OwnLineWithBrace` (in configuration: `OwnLineWithBrace`)
+ As with `OwnLine`, except, unless otherwise prohibited, place a
following open brace (of a function definition) to follow on the same
line.
- .. code-block:: c++
-
- void bar(T t)
- requires C<T> {
- return;
- }
+ ```c++
+ void bar(T t)
+ requires C<T> {
+ return;
+ }
- void bar(T t)
- requires C<T> {}
+ void bar(T t)
+ requires C<T> {}
- template <typename T>
- requires C<T>
- void baz(T t) {
- ...
+ template <typename T>
+ requires C<T>
+ void baz(T t) {
+ ...
+ ```
- * ``RCPS_WithPreceding`` (in configuration: ``WithPreceding``)
+ - `RCPS_WithPreceding` (in configuration: `WithPreceding`)
Try to put the clause together with the preceding part of a declaration.
For class templates: stick to the template declaration.
For function templates: stick to the template declaration.
For function declaration followed by a requires clause: stick to the
parameter list.
- .. code-block:: c++
-
- template <typename T> requires C<T>
- struct Foo {...
+ ```c++
+ template <typename T> requires C<T>
+ struct Foo {...
- template <typename T> requires C<T>
- void bar(T t) {...
+ template <typename T> requires C<T>
+ void bar(T t) {...
- template <typename T>
- void baz(T t) requires C<T>
- {...
+ template <typename T>
+ void baz(T t) requires C<T>
+ {...
+ ```
- * ``RCPS_WithFollowing`` (in configuration: ``WithFollowing``)
- Try to put the ``requires`` clause together with the class or function
+ - `RCPS_WithFollowing` (in configuration: `WithFollowing`)
+ Try to put the `requires` clause together with the class or function
declaration.
- .. code-block:: c++
-
- template <typename T>
- requires C<T> struct Foo {...
+ ```c++
+ template <typename T>
+ requires C<T> struct Foo {...
- template <typename T>
- requires C<T> void bar(T t) {...
+ template <typename T>
+ requires C<T> void bar(T t) {...
- template <typename T>
- void baz(T t)
- requires C<T> {...
+ template <typename T>
+ void baz(T t)
+ requires C<T> {...
+ ```
- * ``RCPS_SingleLine`` (in configuration: ``SingleLine``)
+ - `RCPS_SingleLine` (in configuration: `SingleLine`)
Try to put everything in the same line if possible. Otherwise normal
line breaking rules take over.
- .. code-block:: c++
+ ```c++
+ // Fitting:
+ template <typename T> requires C<T> struct Foo {...
- // Fitting:
- template <typename T> requires C<T> struct Foo {...
+ template <typename T> requires C<T> void bar(T t) {...
- template <typename T> requires C<T> void bar(T t) {...
+ template <typename T> void bar(T t) requires C<T> {...
- template <typename T> void bar(T t) requires C<T> {...
+ // Not fitting, one possible example:
+ template <typename LongName>
+ requires C<LongName>
+ struct Foo {...
- // Not fitting, one possible example:
- template <typename LongName>
- requires C<LongName>
- struct Foo {...
+ template <typename LongName>
+ requires C<LongName>
+ void bar(LongName ln) {
- template <typename LongName>
- requires C<LongName>
- void bar(LongName ln) {
+ template <typename LongName>
+ void bar(LongName ln)
+ requires C<LongName> {
+ ```
- template <typename LongName>
- void bar(LongName ln)
- requires C<LongName> {
+(requiresexpressionindentation)=
-.. _RequiresExpressionIndentation:
+**RequiresExpressionIndentation** (`RequiresExpressionIndentationKind`) {versionbadge}`clang-format 16` {ref}`¶ <RequiresExpressionIndentation>`
-**RequiresExpressionIndentation** (``RequiresExpressionIndentationKind``) :versionbadge:`clang-format 16` :ref:`¶ <RequiresExpressionIndentation>`
- The indentation used for requires expression bodies.
+: The indentation used for requires expression bodies.
Possible values:
- * ``REI_OuterScope`` (in configuration: ``OuterScope``)
+ - `REI_OuterScope` (in configuration: `OuterScope`)
Align requires expression body relative to the indentation level of the
outer scope the requires expression resides in.
This is the default.
- .. code-block:: c++
-
- template <typename T>
- concept C = requires(T t) {
- ...
- }
+ ```c++
+ template <typename T>
+ concept C = requires(T t) {
+ ...
+ }
+ ```
- * ``REI_Keyword`` (in configuration: ``Keyword``)
- Align requires expression body relative to the ``requires`` keyword.
+ - `REI_Keyword` (in configuration: `Keyword`)
+ Align requires expression body relative to the `requires` keyword.
- .. code-block:: c++
+ ```c++
+ template <typename T>
+ concept C = requires(T t) {
+ ...
+ }
+ ```
- template <typename T>
- concept C = requires(T t) {
- ...
- }
+(separatedefinitionblocks)=
-.. _SeparateDefinitionBlocks:
+**SeparateDefinitionBlocks** (`SeparateDefinitionStyle`) {versionbadge}`clang-format 14` {ref}`¶ <SeparateDefinitionBlocks>`
-**SeparateDefinitionBlocks** (``SeparateDefinitionStyle``) :versionbadge:`clang-format 14` :ref:`¶ <SeparateDefinitionBlocks>`
- Specifies the use of empty lines to separate definition blocks, including
+: Specifies the use of empty lines to separate definition blocks, including
classes, structs, enums, and functions.
- .. code-block:: c++
-
- Never v.s. Always
- #include <cstring> #include <cstring>
- struct Foo {
- int a, b, c; struct Foo {
- }; int a, b, c;
- namespace Ns { };
- class Bar {
- public: namespace Ns {
- struct Foobar { class Bar {
- int a; public:
- int b; struct Foobar {
- }; int a;
- private: int b;
- int t; };
- int method1() {
- // ... private:
- } int t;
- enum List {
- ITEM1, int method1() {
- ITEM2 // ...
- }; }
- template<typename T>
- int method2(T x) { enum List {
- // ... ITEM1,
- } ITEM2
- int i, j, k; };
- int method3(int par) {
- // ... template<typename T>
- } int method2(T x) {
- }; // ...
- class C {}; }
- }
- int i, j, k;
+ ```c++
+ Never v.s. Always
+ #include <cstring> #include <cstring>
+ struct Foo {
+ int a, b, c; struct Foo {
+ }; int a, b, c;
+ namespace Ns { };
+ class Bar {
+ public: namespace Ns {
+ struct Foobar { class Bar {
+ int a; public:
+ int b; struct Foobar {
+ }; int a;
+ private: int b;
+ int t; };
+ int method1() {
+ // ... private:
+ } int t;
+ enum List {
+ ITEM1, int method1() {
+ ITEM2 // ...
+ }; }
+ template<typename T>
+ int method2(T x) { enum List {
+ // ... ITEM1,
+ } ITEM2
+ int i, j, k; };
+ int method3(int par) {
+ // ... template<typename T>
+ } int method2(T x) {
+ }; // ...
+ class C {}; }
+ }
+ int i, j, k;
- int method3(int par) {
- // ...
- }
- };
+ int method3(int par) {
+ // ...
+ }
+ };
- class C {};
- }
+ class C {};
+ }
+ ```
Possible values:
- * ``SDS_Leave`` (in configuration: ``Leave``)
+ - `SDS_Leave` (in configuration: `Leave`)
Leave definition blocks as they are.
- * ``SDS_Always`` (in configuration: ``Always``)
+ - `SDS_Always` (in configuration: `Always`)
Insert an empty line between definition blocks.
- * ``SDS_Never`` (in configuration: ``Never``)
+ - `SDS_Never` (in configuration: `Never`)
Remove any empty line between definition blocks.
-.. _ShortNamespaceLines:
+(shortnamespacelines)=
+
+**ShortNamespaceLines** (`Unsigned`) {versionbadge}`clang-format 13` {ref}`¶ <ShortNamespaceLines>`
-**ShortNamespaceLines** (``Unsigned``) :versionbadge:`clang-format 13` :ref:`¶ <ShortNamespaceLines>`
- The maximal number of unwrapped lines that a short namespace spans.
+: The maximal number of unwrapped lines that a short namespace spans.
Defaults to 1.
This determines the maximum length of short namespaces by counting
unwrapped lines (i.e. containing neither opening nor closing
- namespace brace) and makes ``FixNamespaceComments`` omit adding
+ namespace brace) and makes `FixNamespaceComments` omit adding
end comments for those.
- .. code-block:: c++
+ ```c++
+ ShortNamespaceLines: 1 vs. ShortNamespaceLines: 0
+ namespace a { namespace a {
+ int foo; int foo;
+ } } // namespace a
- ShortNamespaceLines: 1 vs. ShortNamespaceLines: 0
- namespace a { namespace a {
- int foo; int foo;
- } } // namespace a
+ ShortNamespaceLines: 1 vs. ShortNamespaceLines: 0
+ namespace b { namespace b {
+ int foo; int foo;
+ int bar; int bar;
+ } // namespace b } // namespace b
+ ```
- ShortNamespaceLines: 1 vs. ShortNamespaceLines: 0
- namespace b { namespace b {
- int foo; int foo;
- int bar; int bar;
- } // namespace b } // namespace b
+(skipmacrodefinitionbody)=
-.. _SkipMacroDefinitionBody:
+**SkipMacroDefinitionBody** (`Boolean`) {versionbadge}`clang-format 18` {ref}`¶ <SkipMacroDefinitionBody>`
-**SkipMacroDefinitionBody** (``Boolean``) :versionbadge:`clang-format 18` :ref:`¶ <SkipMacroDefinitionBody>`
- Do not format macro definition body.
+: Do not format macro definition body.
-.. _SortIncludes:
+(sortincludes)=
-**SortIncludes** (``SortIncludesOptions``) :versionbadge:`clang-format 3.8` :ref:`¶ <SortIncludes>`
- Controls if and how clang-format will sort ``#includes``.
+**SortIncludes** (`SortIncludesOptions`) {versionbadge}`clang-format 3.8` {ref}`¶ <SortIncludes>`
+
+: Controls if and how clang-format will sort `#includes`.
Nested configuration flags:
Includes sorting options.
- * ``bool Enabled`` If ``true``, includes are sorted based on the other suboptions below.
- (``Never`` is deprecated by ``Enabled: false``.)
-
- * ``bool IgnoreCase`` Whether or not includes are sorted in a case-insensitive fashion.
- (``CaseSensitive`` and ``CaseInsensitive`` are deprecated by
- ``IgnoreCase: false`` and ``IgnoreCase: true``, respectively.)
+ - `bool Enabled` If `true`, includes are sorted based on the other suboptions below.
+ (`Never` is deprecated by `Enabled: false`.)
- .. code-block:: c++
+ - `bool IgnoreCase` Whether or not includes are sorted in a case-insensitive fashion.
+ (`CaseSensitive` and `CaseInsensitive` are deprecated by
+ `IgnoreCase: false` and `IgnoreCase: true`, respectively.)
- true: false:
- #include "A/B.h" vs. #include "A/B.h"
- #include "A/b.h" #include "A/b.h"
- #include "a/b.h" #include "B/A.h"
- #include "B/A.h" #include "B/a.h"
- #include "B/a.h" #include "a/b.h"
+ ```c++
+ true: false:
+ #include "A/B.h" vs. #include "A/B.h"
+ #include "A/b.h" #include "A/b.h"
+ #include "a/b.h" #include "B/A.h"
+ #include "B/A.h" #include "B/a.h"
+ #include "B/a.h" #include "a/b.h"
+ ```
- * ``bool IgnoreExtension`` When sorting includes in each block, only take file extensions into
+ - `bool IgnoreExtension` When sorting includes in each block, only take file extensions into
account if two includes compare equal otherwise.
- .. code-block:: c++
+ ```c++
+ true: false:
+ # include "A.h" vs. # include "A-util.h"
+ # include "A.inc" # include "A.h"
+ # include "A-util.h" # include "A.inc"
+ ```
- true: false:
- # include "A.h" vs. # include "A-util.h"
- # include "A.inc" # include "A.h"
- # include "A-util.h" # include "A.inc"
-
- * ``bool Natural`` Whether or not includes are sorted by natural ordering i.e., whether
+ - `bool Natural` Whether or not includes are sorted by natural ordering i.e., whether
embedded runs of digits are compared as numbers rather than sequences of
characters.
- .. code-block:: c++
+ ```c++
+ true: false:
+ #include "A2.h" vs. #include "A10.h"
+ #include "A10.h" #include "A2.h"
+ ```
- true: false:
- #include "A2.h" vs. #include "A10.h"
- #include "A10.h" #include "A2.h"
+(sortjavastaticimport)=
-.. _SortJavaStaticImport:
+**SortJavaStaticImport** (`SortJavaStaticImportOptions`) {versionbadge}`clang-format 12` {ref}`¶ <SortJavaStaticImport>`
-**SortJavaStaticImport** (``SortJavaStaticImportOptions``) :versionbadge:`clang-format 12` :ref:`¶ <SortJavaStaticImport>`
- When sorting Java imports, by default static imports are placed before
- non-static imports. If ``JavaStaticImportAfterImport`` is ``After``,
+: When sorting Java imports, by default static imports are placed before
+ non-static imports. If `JavaStaticImportAfterImport` is `After`,
static imports are placed after non-static imports.
Possible values:
- * ``SJSIO_Before`` (in configuration: ``Before``)
+ - `SJSIO_Before` (in configuration: `Before`)
Static imports are placed before non-static imports.
- .. code-block:: java
-
- import static org.example.function1;
+ ```java
+ import static org.example.function1;
- import org.example.ClassA;
+ import org.example.ClassA;
+ ```
- * ``SJSIO_After`` (in configuration: ``After``)
+ - `SJSIO_After` (in configuration: `After`)
Static imports are placed after non-static imports.
- .. code-block:: java
+ ```java
+ import org.example.ClassA;
- import org.example.ClassA;
+ import static org.example.function1;
+ ```
- import static org.example.function1;
+(sortusingdeclarations)=
-.. _SortUsingDeclarations:
+**SortUsingDeclarations** (`SortUsingDeclarationsOptions`) {versionbadge}`clang-format 5` {ref}`¶ <SortUsingDeclarations>`
-**SortUsingDeclarations** (``SortUsingDeclarationsOptions``) :versionbadge:`clang-format 5` :ref:`¶ <SortUsingDeclarations>`
- Controls if and how clang-format will sort using declarations.
+: Controls if and how clang-format will sort using declarations.
Possible values:
- * ``SUD_Never`` (in configuration: ``Never``)
+ - `SUD_Never` (in configuration: `Never`)
Using declarations are never sorted.
- .. code-block:: c++
+ ```c++
+ using std::chrono::duration_cast;
+ using std::move;
+ using boost::regex;
+ using boost::regex_constants::icase;
+ using std::string;
+ ```
- using std::chrono::duration_cast;
- using std::move;
- using boost::regex;
- using boost::regex_constants::icase;
- using std::string;
-
- * ``SUD_Lexicographic`` (in configuration: ``Lexicographic``)
+ - `SUD_Lexicographic` (in configuration: `Lexicographic`)
Using declarations are sorted in the order defined as follows:
- Split the strings by ``::`` and discard any initial empty strings. Sort
+ Split the strings by `::` and discard any initial empty strings. Sort
the lists of names lexicographically, and within those groups, names are
in case-insensitive lexicographic order.
- .. code-block:: c++
-
- using boost::regex;
- using boost::regex_constants::icase;
- using std::chrono::duration_cast;
- using std::move;
- using std::string;
+ ```c++
+ using boost::regex;
+ using boost::regex_constants::icase;
+ using std::chrono::duration_cast;
+ using std::move;
+ using std::string;
+ ```
- * ``SUD_LexicographicNumeric`` (in configuration: ``LexicographicNumeric``)
+ - `SUD_LexicographicNumeric` (in configuration: `LexicographicNumeric`)
Using declarations are sorted in the order defined as follows:
- Split the strings by ``::`` and discard any initial empty strings. The
+ Split the strings by `::` and discard any initial empty strings. The
last element of each list is a non-namespace name; all others are
namespace names. Sort the lists of names lexicographically, where the
sort order of individual names is that all non-namespace names come
before all namespace names, and within those groups, names are in
case-insensitive lexicographic order.
- .. code-block:: c++
+ ```c++
+ using boost::regex;
+ using boost::regex_constants::icase;
+ using std::move;
+ using std::string;
+ using std::chrono::duration_cast;
+ ```
- using boost::regex;
- using boost::regex_constants::icase;
- using std::move;
- using std::string;
- using std::chrono::duration_cast;
+(spaceaftercstylecast)=
-.. _SpaceAfterCStyleCast:
+**SpaceAfterCStyleCast** (`Boolean`) {versionbadge}`clang-format 3.5` {ref}`¶ <SpaceAfterCStyleCast>`
-**SpaceAfterCStyleCast** (``Boolean``) :versionbadge:`clang-format 3.5` :ref:`¶ <SpaceAfterCStyleCast>`
- If ``true``, a space is inserted after C style casts.
+: If `true`, a space is inserted after C style casts.
- .. code-block:: c++
+ ```c++
+ true: false:
+ (int) i; vs. (int)i;
+ ```
- true: false:
- (int) i; vs. (int)i;
+(spaceafterlogicalnot)=
-.. _SpaceAfterLogicalNot:
+**SpaceAfterLogicalNot** (`Boolean`) {versionbadge}`clang-format 9` {ref}`¶ <SpaceAfterLogicalNot>`
-**SpaceAfterLogicalNot** (``Boolean``) :versionbadge:`clang-format 9` :ref:`¶ <SpaceAfterLogicalNot>`
- If ``true``, a space is inserted after the logical not operator (``!``).
+: If `true`, a space is inserted after the logical not operator (`!`).
- .. code-block:: c++
+ ```c++
+ true: false:
+ ! someExpression(); vs. !someExpression();
+ ```
- true: false:
- ! someExpression(); vs. !someExpression();
+(spaceafteroperatorkeyword)=
-.. _SpaceAfterOperatorKeyword:
+**SpaceAfterOperatorKeyword** (`Boolean`) {versionbadge}`clang-format 21` {ref}`¶ <SpaceAfterOperatorKeyword>`
-**SpaceAfterOperatorKeyword** (``Boolean``) :versionbadge:`clang-format 21` :ref:`¶ <SpaceAfterOperatorKeyword>`
- If ``true``, a space will be inserted after the ``operator`` keyword.
+: If `true`, a space will be inserted after the `operator` keyword.
- .. code-block:: c++
+ ```c++
+ true: false:
+ bool operator ==(int a); vs. bool operator==(int a);
+ ```
- true: false:
- bool operator ==(int a); vs. bool operator==(int a);
+(spaceaftertemplatekeyword)=
-.. _SpaceAfterTemplateKeyword:
+**SpaceAfterTemplateKeyword** (`Boolean`) {versionbadge}`clang-format 4` {ref}`¶ <SpaceAfterTemplateKeyword>`
-**SpaceAfterTemplateKeyword** (``Boolean``) :versionbadge:`clang-format 4` :ref:`¶ <SpaceAfterTemplateKeyword>`
- If ``true``, a space will be inserted after the ``template`` keyword.
+: If `true`, a space will be inserted after the `template` keyword.
- .. code-block:: c++
+ ```c++
+ true: false:
+ template <int> void foo(); vs. template<int> void foo();
+ ```
- true: false:
- template <int> void foo(); vs. template<int> void foo();
+(spacearoundpointerqualifiers)=
-.. _SpaceAroundPointerQualifiers:
+**SpaceAroundPointerQualifiers** (`SpaceAroundPointerQualifiersStyle`) {versionbadge}`clang-format 12` {ref}`¶ <SpaceAroundPointerQualifiers>`
-**SpaceAroundPointerQualifiers** (``SpaceAroundPointerQualifiersStyle``) :versionbadge:`clang-format 12` :ref:`¶ <SpaceAroundPointerQualifiers>`
- Defines in which cases to put a space before or after pointer qualifiers
+: Defines in which cases to put a space before or after pointer qualifiers
Possible values:
- * ``SAPQ_Default`` (in configuration: ``Default``)
+ - `SAPQ_Default` (in configuration: `Default`)
Don't ensure spaces around pointer qualifiers and use PointerAlignment
instead.
- .. code-block:: c++
+ ```c++
+ PointerAlignment: Left PointerAlignment: Right
+ void* const* x = NULL; vs. void *const *x = NULL;
+ ```
- PointerAlignment: Left PointerAlignment: Right
- void* const* x = NULL; vs. void *const *x = NULL;
-
- * ``SAPQ_Before`` (in configuration: ``Before``)
+ - `SAPQ_Before` (in configuration: `Before`)
Ensure that there is a space before pointer qualifiers.
- .. code-block:: c++
-
- PointerAlignment: Left PointerAlignment: Right
- void* const* x = NULL; vs. void * const *x = NULL;
+ ```c++
+ PointerAlignment: Left PointerAlignment: Right
+ void* const* x = NULL; vs. void * const *x = NULL;
+ ```
- * ``SAPQ_After`` (in configuration: ``After``)
+ - `SAPQ_After` (in configuration: `After`)
Ensure that there is a space after pointer qualifiers.
- .. code-block:: c++
+ ```c++
+ PointerAlignment: Left PointerAlignment: Right
+ void* const * x = NULL; vs. void *const *x = NULL;
+ ```
- PointerAlignment: Left PointerAlignment: Right
- void* const * x = NULL; vs. void *const *x = NULL;
-
- * ``SAPQ_Both`` (in configuration: ``Both``)
+ - `SAPQ_Both` (in configuration: `Both`)
Ensure that there is a space both before and after pointer qualifiers.
- .. code-block:: c++
+ ```c++
+ PointerAlignment: Left PointerAlignment: Right
+ void* const * x = NULL; vs. void * const *x = NULL;
+ ```
- PointerAlignment: Left PointerAlignment: Right
- void* const * x = NULL; vs. void * const *x = NULL;
+(spacebeforeassignmentoperators)=
-.. _SpaceBeforeAssignmentOperators:
+**SpaceBeforeAssignmentOperators** (`Boolean`) {versionbadge}`clang-format 3.7` {ref}`¶ <SpaceBeforeAssignmentOperators>`
-**SpaceBeforeAssignmentOperators** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpaceBeforeAssignmentOperators>`
- If ``false``, spaces will be removed before assignment operators.
+: If `false`, spaces will be removed before assignment operators.
- .. code-block:: c++
+ ```c++
+ true: false:
+ int a = 5; vs. int a= 5;
+ a += 42; a+= 42;
+ ```
- true: false:
- int a = 5; vs. int a= 5;
- a += 42; a+= 42;
+(spacebeforecasecolon)=
-.. _SpaceBeforeCaseColon:
+**SpaceBeforeCaseColon** (`Boolean`) {versionbadge}`clang-format 12` {ref}`¶ <SpaceBeforeCaseColon>`
-**SpaceBeforeCaseColon** (``Boolean``) :versionbadge:`clang-format 12` :ref:`¶ <SpaceBeforeCaseColon>`
- If ``false``, spaces will be removed before case colon.
+: If `false`, spaces will be removed before case colon.
- .. code-block:: c++
+ ```c++
+ true: false
+ switch (x) { vs. switch (x) {
+ case 1 : break; case 1: break;
+ } }
+ ```
- true: false
- switch (x) { vs. switch (x) {
- case 1 : break; case 1: break;
- } }
+(spacebeforecpp11bracedlist)=
-.. _SpaceBeforeCpp11BracedList:
+**SpaceBeforeCpp11BracedList** (`Boolean`) {versionbadge}`clang-format 7` {ref}`¶ <SpaceBeforeCpp11BracedList>`
-**SpaceBeforeCpp11BracedList** (``Boolean``) :versionbadge:`clang-format 7` :ref:`¶ <SpaceBeforeCpp11BracedList>`
- If ``true``, a space will be inserted before a C++11 braced list
+: If `true`, a space will be inserted before a C++11 braced list
used to initialize an object (after the preceding identifier or type).
- .. code-block:: c++
+ ```c++
+ true: false:
+ Foo foo { bar }; vs. Foo foo{ bar };
+ Foo {}; Foo{};
+ vector<int> { 1, 2, 3 }; vector<int>{ 1, 2, 3 };
+ new int[3] { 1, 2, 3 }; new int[3]{ 1, 2, 3 };
+ ```
- true: false:
- Foo foo { bar }; vs. Foo foo{ bar };
- Foo {}; Foo{};
- vector<int> { 1, 2, 3 }; vector<int>{ 1, 2, 3 };
- new int[3] { 1, 2, 3 }; new int[3]{ 1, 2, 3 };
+(spacebeforectorinitializercolon)=
-.. _SpaceBeforeCtorInitializerColon:
+**SpaceBeforeCtorInitializerColon** (`Boolean`) {versionbadge}`clang-format 7` {ref}`¶ <SpaceBeforeCtorInitializerColon>`
-**SpaceBeforeCtorInitializerColon** (``Boolean``) :versionbadge:`clang-format 7` :ref:`¶ <SpaceBeforeCtorInitializerColon>`
- If ``false``, spaces will be removed before constructor initializer
+: If `false`, spaces will be removed before constructor initializer
colon.
- .. code-block:: c++
+ ```c++
+ true: false:
+ Foo::Foo() : a(a) {} Foo::Foo(): a(a) {}
+ ```
- true: false:
- Foo::Foo() : a(a) {} Foo::Foo(): a(a) {}
+(spacebeforeenumunderlyingtypecolon)=
-.. _SpaceBeforeEnumUnderlyingTypeColon:
+**SpaceBeforeEnumUnderlyingTypeColon** (`Boolean`) {versionbadge}`clang-format 23` {ref}`¶ <SpaceBeforeEnumUnderlyingTypeColon>`
-**SpaceBeforeEnumUnderlyingTypeColon** (``Boolean``) :versionbadge:`clang-format 23` :ref:`¶ <SpaceBeforeEnumUnderlyingTypeColon>`
- If ``false``, spaces will be removed before enum underlying type colon.
+: If `false`, spaces will be removed before enum underlying type colon.
- .. code-block:: c++
+ ```c++
+ true: false:
+ enum E : int {} enum E: int {}
+ ```
- true: false:
- enum E : int {} enum E: int {}
+(spacebeforeinheritancecolon)=
-.. _SpaceBeforeInheritanceColon:
+**SpaceBeforeInheritanceColon** (`Boolean`) {versionbadge}`clang-format 7` {ref}`¶ <SpaceBeforeInheritanceColon>`
-**SpaceBeforeInheritanceColon** (``Boolean``) :versionbadge:`clang-format 7` :ref:`¶ <SpaceBeforeInheritanceColon>`
- If ``false``, spaces will be removed before inheritance colon.
+: If `false`, spaces will be removed before inheritance colon.
- .. code-block:: c++
+ ```c++
+ true: false:
+ class Foo : Bar {} vs. class Foo: Bar {}
+ ```
- true: false:
- class Foo : Bar {} vs. class Foo: Bar {}
+(spacebeforejsoncolon)=
-.. _SpaceBeforeJsonColon:
+**SpaceBeforeJsonColon** (`Boolean`) {versionbadge}`clang-format 17` {ref}`¶ <SpaceBeforeJsonColon>`
-**SpaceBeforeJsonColon** (``Boolean``) :versionbadge:`clang-format 17` :ref:`¶ <SpaceBeforeJsonColon>`
- If ``true``, a space will be added before a JSON colon. For other
- languages, e.g. JavaScript, use ``SpacesInContainerLiterals`` instead.
+: If `true`, a space will be added before a JSON colon. For other
+ languages, e.g. JavaScript, use `SpacesInContainerLiterals` instead.
- .. code-block:: c++
+ ```c++
+ true: false:
+ { {
+ "key" : "value" vs. "key": "value"
+ } }
+ ```
- true: false:
- { {
- "key" : "value" vs. "key": "value"
- } }
+(spacebeforeparens)=
-.. _SpaceBeforeParens:
+**SpaceBeforeParens** (`SpaceBeforeParensStyle`) {versionbadge}`clang-format 3.5` {ref}`¶ <SpaceBeforeParens>`
-**SpaceBeforeParens** (``SpaceBeforeParensStyle``) :versionbadge:`clang-format 3.5` :ref:`¶ <SpaceBeforeParens>`
- Defines in which cases to put a space before opening parentheses.
+: Defines in which cases to put a space before opening parentheses.
Possible values:
- * ``SBPO_Never`` (in configuration: ``Never``)
- This is **deprecated** and replaced by ``Custom`` below, with all
- ``SpaceBeforeParensOptions`` but ``AfterPlacementOperator`` set to
- ``false``.
+ - `SBPO_Never` (in configuration: `Never`)
+ This is **deprecated** and replaced by `Custom` below, with all
+ `SpaceBeforeParensOptions` but `AfterPlacementOperator` set to
+ `false`.
- * ``SBPO_ControlStatements`` (in configuration: ``ControlStatements``)
+ - `SBPO_ControlStatements` (in configuration: `ControlStatements`)
Put a space before opening parentheses only after control statement
- keywords (``for/if/while...``).
-
- .. code-block:: c++
+ keywords (`for/if/while...`).
- void f() {
- if (true) {
- f();
- }
- }
+ ```c++
+ void f() {
+ if (true) {
+ f();
+ }
+ }
+ ```
- * ``SBPO_ControlStatementsExceptControlMacros`` (in configuration: ``ControlStatementsExceptControlMacros``)
- Same as ``SBPO_ControlStatements`` except this option doesn't apply to
+ - `SBPO_ControlStatementsExceptControlMacros` (in configuration: `ControlStatementsExceptControlMacros`)
+ Same as `SBPO_ControlStatements` except this option doesn't apply to
ForEach and If macros. This is useful in projects where ForEach/If
macros are treated as function calls instead of control statements.
- ``SBPO_ControlStatementsExceptForEachMacros`` remains an alias for
+ `SBPO_ControlStatementsExceptForEachMacros` remains an alias for
backward compatibility.
- .. code-block:: c++
-
- void f() {
- Q_FOREACH(...) {
- f();
- }
- }
+ ```c++
+ void f() {
+ Q_FOREACH(...) {
+ f();
+ }
+ }
+ ```
- * ``SBPO_NonEmptyParentheses`` (in configuration: ``NonEmptyParentheses``)
+ - `SBPO_NonEmptyParentheses` (in configuration: `NonEmptyParentheses`)
Put a space before opening parentheses only if the parentheses are not
empty.
- .. code-block:: c++
-
- void() {
- if (true) {
- f();
- g (x, y, z);
- }
+ ```c++
+ void() {
+ if (true) {
+ f();
+ g (x, y, z);
}
+ }
+ ```
- * ``SBPO_Always`` (in configuration: ``Always``)
+ - `SBPO_Always` (in configuration: `Always`)
Always put a space before opening parentheses, except when it's
prohibited by the syntax rules (in function-like macro definitions) or
when determined by other style rules (after unary operators, opening
parentheses, etc.)
- .. code-block:: c++
-
- void f () {
- if (true) {
- f ();
- }
- }
+ ```c++
+ void f () {
+ if (true) {
+ f ();
+ }
+ }
+ ```
- * ``SBPO_Custom`` (in configuration: ``Custom``)
+ - `SBPO_Custom` (in configuration: `Custom`)
Configure each individual space before parentheses in
- ``SpaceBeforeParensOptions``.
+ `SpaceBeforeParensOptions`.
-.. _SpaceBeforeParensOptions:
+(spacebeforeparensoptions)=
-**SpaceBeforeParensOptions** (``SpaceBeforeParensCustom``) :versionbadge:`clang-format 14` :ref:`¶ <SpaceBeforeParensOptions>`
- Control of individual space before parentheses.
+**SpaceBeforeParensOptions** (`SpaceBeforeParensCustom`) {versionbadge}`clang-format 14` {ref}`¶ <SpaceBeforeParensOptions>`
- If ``SpaceBeforeParens`` is set to ``Custom``, use this to specify
+: Control of individual space before parentheses.
+
+ If `SpaceBeforeParens` is set to `Custom`, use this to specify
how each individual space before parentheses case should be handled.
Otherwise, this is ignored.
- .. code-block:: yaml
-
- # Example of usage:
- SpaceBeforeParens: Custom
- SpaceBeforeParensOptions:
- AfterControlStatements: true
- AfterFunctionDefinitionName: true
+ ```yaml
+ # Example of usage:
+ SpaceBeforeParens: Custom
+ SpaceBeforeParensOptions:
+ AfterControlStatements: true
+ AfterFunctionDefinitionName: true
+ ```
Nested configuration flags:
Precise control over the spacing before parentheses.
- .. code-block:: c++
+ ```yaml
+ # Should be declared this way:
+ SpaceBeforeParens: Custom
+ SpaceBeforeParensOptions:
+ AfterControlStatements: true
+ AfterFunctionDefinitionName: true
+ ```
- # Should be declared this way:
- SpaceBeforeParens: Custom
- SpaceBeforeParensOptions:
- AfterControlStatements: true
- AfterFunctionDefinitionName: true
-
- * ``bool AfterControlStatements`` If ``true``, put space between control statement keywords
+ - `bool AfterControlStatements` If `true`, put space between control statement keywords
(for/if/while...) and opening parentheses.
- .. code-block:: c++
-
- true: false:
- if (...) {} vs. if(...) {}
+ ```c++
+ true: false:
+ if (...) {} vs. if(...) {}
+ ```
- * ``bool AfterForeachMacros`` If ``true``, put space between foreach macros and opening parentheses.
+ - `bool AfterForeachMacros` If `true`, put space between foreach macros and opening parentheses.
- .. code-block:: c++
+ ```c++
+ true: false:
+ FOREACH (...) vs. FOREACH(...)
+ <loop-body> <loop-body>
+ ```
- true: false:
- FOREACH (...) vs. FOREACH(...)
- <loop-body> <loop-body>
-
- * ``bool AfterFunctionDeclarationName`` If ``true``, put a space between function declaration name and opening
+ - `bool AfterFunctionDeclarationName` If `true`, put a space between function declaration name and opening
parentheses.
- .. code-block:: c++
-
- true: false:
- void f (); vs. void f();
+ ```c++
+ true: false:
+ void f (); vs. void f();
+ ```
- * ``bool AfterFunctionDefinitionName`` If ``true``, put a space between function definition name and opening
+ - `bool AfterFunctionDefinitionName` If `true`, put a space between function definition name and opening
parentheses.
- .. code-block:: c++
-
- true: false:
- void f () {} vs. void f() {}
-
- * ``bool AfterIfMacros`` If ``true``, put space between if macros and opening parentheses.
+ ```c++
+ true: false:
+ void f () {} vs. void f() {}
+ ```
- .. code-block:: c++
+ - `bool AfterIfMacros` If `true`, put space between if macros and opening parentheses.
- true: false:
- IF (...) vs. IF(...)
- <conditional-body> <conditional-body>
+ ```c++
+ true: false:
+ IF (...) vs. IF(...)
+ <conditional-body> <conditional-body>
+ ```
- * ``bool AfterNot`` If ``true``, put a space between alternative operator ``not`` and the
+ - `bool AfterNot` If `true`, put a space between alternative operator `not` and the
opening parenthesis.
- .. code-block:: c++
+ ```c++
+ true: false:
+ return not (a || b); vs. return not(a || b);
+ ```
- true: false:
- return not (a || b); vs. return not(a || b);
-
- * ``bool AfterOverloadedOperator`` If ``true``, put a space between operator overloading and opening
+ - `bool AfterOverloadedOperator` If `true`, put a space between operator overloading and opening
parentheses.
- .. code-block:: c++
-
- true: false:
- void operator++ (int a); vs. void operator++(int a);
- object.operator++ (10); object.operator++(10);
+ ```c++
+ true: false:
+ void operator++ (int a); vs. void operator++(int a);
+ object.operator++ (10); object.operator++(10);
+ ```
- * ``bool AfterPlacementOperator`` If ``true``, put a space between operator ``new``/``delete`` and opening
+ - `bool AfterPlacementOperator` If `true`, put a space between operator `new`/`delete` and opening
parenthesis.
- .. code-block:: c++
+ ```c++
+ true: false:
+ new (buf) T; vs. new(buf) T;
+ delete (buf) T; delete(buf) T;
+ ```
- true: false:
- new (buf) T; vs. new(buf) T;
- delete (buf) T; delete(buf) T;
-
- * ``bool AfterRequiresInClause`` If ``true``, put space between requires keyword in a requires clause and
+ - `bool AfterRequiresInClause` If `true`, put space between requires keyword in a requires clause and
opening parentheses, if there is one.
- .. code-block:: c++
-
- true: false:
- template<typename T> vs. template<typename T>
- requires (A<T> && B<T>) requires(A<T> && B<T>)
- ... ...
+ ```c++
+ true: false:
+ template<typename T> vs. template<typename T>
+ requires (A<T> && B<T>) requires(A<T> && B<T>)
+ ... ...
+ ```
- * ``bool AfterRequiresInExpression`` If ``true``, put space between requires keyword in a requires expression
+ - `bool AfterRequiresInExpression` If `true`, put space between requires keyword in a requires expression
and opening parentheses.
- .. code-block:: c++
+ ```c++
+ true: false:
+ template<typename T> vs. template<typename T>
+ concept C = requires (T t) { concept C = requires(T t) {
+ ... ...
+ } }
+ ```
- true: false:
- template<typename T> vs. template<typename T>
- concept C = requires (T t) { concept C = requires(T t) {
- ... ...
- } }
-
- * ``bool BeforeNonEmptyParentheses`` If ``true``, put a space before opening parentheses only if the
+ - `bool BeforeNonEmptyParentheses` If `true`, put a space before opening parentheses only if the
parentheses are not empty.
- .. code-block:: c++
+ ```c++
+ true: false:
+ void f (int a); vs. void f();
+ f (a); f();
+ ```
- true: false:
- void f (int a); vs. void f();
- f (a); f();
+(spacebeforerangebasedforloopcolon)=
-.. _SpaceBeforeRangeBasedForLoopColon:
+**SpaceBeforeRangeBasedForLoopColon** (`Boolean`) {versionbadge}`clang-format 7` {ref}`¶ <SpaceBeforeRangeBasedForLoopColon>`
-**SpaceBeforeRangeBasedForLoopColon** (``Boolean``) :versionbadge:`clang-format 7` :ref:`¶ <SpaceBeforeRangeBasedForLoopColon>`
- If ``false``, spaces will be removed before range-based for loop
+: If `false`, spaces will be removed before range-based for loop
colon.
- .. code-block:: c++
+ ```c++
+ true: false:
+ for (auto v : values) {} vs. for(auto v: values) {}
+ ```
- true: false:
- for (auto v : values) {} vs. for(auto v: values) {}
+(spacebeforesquarebrackets)=
-.. _SpaceBeforeSquareBrackets:
+**SpaceBeforeSquareBrackets** (`Boolean`) {versionbadge}`clang-format 10` {ref}`¶ <SpaceBeforeSquareBrackets>`
-**SpaceBeforeSquareBrackets** (``Boolean``) :versionbadge:`clang-format 10` :ref:`¶ <SpaceBeforeSquareBrackets>`
- If ``true``, spaces will be before ``[``.
- Lambdas will not be affected. Only the first ``[`` will get a space added.
+: If `true`, spaces will be before `[`.
+ Lambdas will not be affected. Only the first `[` will get a space added.
- .. code-block:: c++
+ ```c++
+ true: false:
+ int a [5]; vs. int a[5];
+ int a [5][5]; vs. int a[5][5];
+ ```
- true: false:
- int a [5]; vs. int a[5];
- int a [5][5]; vs. int a[5][5];
+(spaceinemptyblock)=
-.. _SpaceInEmptyBlock:
+**SpaceInEmptyBlock** (`Boolean`) {versionbadge}`clang-format 10` {ref}`¶ <SpaceInEmptyBlock>`
-**SpaceInEmptyBlock** (``Boolean``) :versionbadge:`clang-format 10` :ref:`¶ <SpaceInEmptyBlock>`
- This option is **deprecated**. See ``Block`` of ``SpaceInEmptyBraces``.
+: This option is **deprecated**. See `Block` of `SpaceInEmptyBraces`.
-.. _SpaceInEmptyBraces:
+(spaceinemptybraces)=
-**SpaceInEmptyBraces** (``SpaceInEmptyBracesStyle``) :versionbadge:`clang-format 22` :ref:`¶ <SpaceInEmptyBraces>`
- Specifies when to insert a space in empty braces.
+**SpaceInEmptyBraces** (`SpaceInEmptyBracesStyle`) {versionbadge}`clang-format 22` {ref}`¶ <SpaceInEmptyBraces>`
- .. note::
+: Specifies when to insert a space in empty braces.
- This option doesn't apply to initializer braces if
- ``Cpp11BracedListStyle`` is not ``Block``.
+ :::{note}
+ This option doesn't apply to initializer braces if
+ `Cpp11BracedListStyle` is not `Block`.
+ :::
Possible values:
- * ``SIEB_Always`` (in configuration: ``Always``)
+ - `SIEB_Always` (in configuration: `Always`)
Always insert a space in empty braces.
- .. code-block:: c++
-
- void f() { }
- class Unit { };
- auto a = [] { };
- int x{ };
+ ```c++
+ void f() { }
+ class Unit { };
+ auto a = [] { };
+ int x{ };
+ ```
- * ``SIEB_Block`` (in configuration: ``Block``)
+ - `SIEB_Block` (in configuration: `Block`)
Only insert a space in empty blocks.
- .. code-block:: c++
+ ```c++
+ void f() { }
+ class Unit { };
+ auto a = [] { };
+ int x{};
+ ```
- void f() { }
- class Unit { };
- auto a = [] { };
- int x{};
-
- * ``SIEB_Never`` (in configuration: ``Never``)
+ - `SIEB_Never` (in configuration: `Never`)
Never insert a space in empty braces.
- .. code-block:: c++
+ ```c++
+ void f() {}
+ class Unit {};
+ auto a = [] {};
+ int x{};
+ ```
+
- void f() {}
- class Unit {};
- auto a = [] {};
- int x{};
+(spaceinemptyparentheses)=
+**SpaceInEmptyParentheses** (`Boolean`) {versionbadge}`clang-format 3.7` {ref}`¶ <SpaceInEmptyParentheses>`
-.. _SpaceInEmptyParentheses:
+: If `true`, spaces may be inserted into `()`.
+ This option is **deprecated**. See `InEmptyParentheses` of
+ `SpacesInParensOptions`.
-**SpaceInEmptyParentheses** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpaceInEmptyParentheses>`
- If ``true``, spaces may be inserted into ``()``.
- This option is **deprecated**. See ``InEmptyParentheses`` of
- ``SpacesInParensOptions``.
+(spacesbeforetrailingcomments)=
-.. _SpacesBeforeTrailingComments:
+**SpacesBeforeTrailingComments** (`Unsigned`) {versionbadge}`clang-format 3.7` {ref}`¶ <SpacesBeforeTrailingComments>`
-**SpacesBeforeTrailingComments** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpacesBeforeTrailingComments>`
- The number of spaces before trailing line comments
- (``//`` - comments).
+: The number of spaces before trailing line comments
+ (`//` - comments).
- This does not affect trailing block comments (``/*`` - comments) as those
+ This does not affect trailing block comments (`/*` - comments) as those
commonly have
diff erent usage patterns and a number of special cases. In
the case of Verilog, it doesn't affect a comment right after the opening
parenthesis in the port or parameter list in a module header, because it
is probably for the port on the following line instead of the parenthesis
it follows.
- .. code-block:: c++
+ ```c++
+ SpacesBeforeTrailingComments: 3
+ void f() {
+ if (true) { // foo1
+ f(); // bar
+ } // foo
+ }
+ ```
- SpacesBeforeTrailingComments: 3
- void f() {
- if (true) { // foo1
- f(); // bar
- } // foo
- }
+(spacesinangles)=
-.. _SpacesInAngles:
+**SpacesInAngles** (`SpacesInAnglesStyle`) {versionbadge}`clang-format 3.4` {ref}`¶ <SpacesInAngles>`
-**SpacesInAngles** (``SpacesInAnglesStyle``) :versionbadge:`clang-format 3.4` :ref:`¶ <SpacesInAngles>`
- The SpacesInAnglesStyle to use for template argument lists.
+: The SpacesInAnglesStyle to use for template argument lists.
Possible values:
- * ``SIAS_Never`` (in configuration: ``Never``)
- Remove spaces after ``<`` and before ``>``.
+ - `SIAS_Never` (in configuration: `Never`)
+ Remove spaces after `<` and before `>`.
- .. code-block:: c++
+ ```c++
+ static_cast<int>(arg);
+ std::function<void(int)> fct;
+ ```
- static_cast<int>(arg);
- std::function<void(int)> fct;
+ - `SIAS_Always` (in configuration: `Always`)
+ Add spaces after `<` and before `>`.
- * ``SIAS_Always`` (in configuration: ``Always``)
- Add spaces after ``<`` and before ``>``.
+ ```c++
+ static_cast< int >(arg);
+ std::function< void(int) > fct;
+ ```
- .. code-block:: c++
+ - `SIAS_Leave` (in configuration: `Leave`)
+ Keep a single space after `<` and before `>` if any spaces were
+ present. Option `Standard: Cpp03` takes precedence.
- static_cast< int >(arg);
- std::function< void(int) > fct;
- * ``SIAS_Leave`` (in configuration: ``Leave``)
- Keep a single space after ``<`` and before ``>`` if any spaces were
- present. Option ``Standard: Cpp03`` takes precedence.
+(spacesinblockcomments)=
+**SpacesInBlockComments** (`SpacesInBlockCommentsStyle`) {versionbadge}`clang-format 24` {ref}`¶ <SpacesInBlockComments>`
-.. _SpacesInBlockComments:
-
-**SpacesInBlockComments** (``SpacesInBlockCommentsStyle``) :versionbadge:`clang-format 24` :ref:`¶ <SpacesInBlockComments>`
- The SpacesInBlockCommentsStyle to use for ordinary block comments.
- Documentation comments such as ``/** ... */`` and ``/*! ... */``
- and parameter comments ending with ``=`` before the closing ``*/`` are
+: The SpacesInBlockCommentsStyle to use for ordinary block comments.
+ Documentation comments such as `/** ... */` and `/*! ... */`
+ and parameter comments ending with `=` before the closing `*/` are
left unchanged.
Possible values:
- * ``SIBCS_Never`` (in configuration: ``Never``)
- Remove spaces after ``/*`` and before ``*/``.
+ - `SIBCS_Never` (in configuration: `Never`)
+ Remove spaces after `/*` and before `*/`.
- .. code-block:: c++
+ ```c++
+ /*comment*/
+ ```
- /*comment*/
+ - `SIBCS_Always` (in configuration: `Always`)
+ Add spaces after `/*` and before `*/`.
- * ``SIBCS_Always`` (in configuration: ``Always``)
- Add spaces after ``/*`` and before ``*/``.
+ ```c++
+ /* comment */
+ ```
- .. code-block:: c++
+ - `SIBCS_Leave` (in configuration: `Leave`)
+ Leave existing spaces unchanged.
- /* comment */
- * ``SIBCS_Leave`` (in configuration: ``Leave``)
- Leave existing spaces unchanged.
+(spacesincstylecastparentheses)=
+**SpacesInCStyleCastParentheses** (`Boolean`) {versionbadge}`clang-format 3.7` {ref}`¶ <SpacesInCStyleCastParentheses>`
-.. _SpacesInCStyleCastParentheses:
+: If `true`, spaces may be inserted into C style casts.
+ This option is **deprecated**. See `InCStyleCasts` of
+ `SpacesInParensOptions`.
-**SpacesInCStyleCastParentheses** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpacesInCStyleCastParentheses>`
- If ``true``, spaces may be inserted into C style casts.
- This option is **deprecated**. See ``InCStyleCasts`` of
- ``SpacesInParensOptions``.
+(spacesinconditionalstatement)=
-.. _SpacesInConditionalStatement:
+**SpacesInConditionalStatement** (`Boolean`) {versionbadge}`clang-format 10` {ref}`¶ <SpacesInConditionalStatement>`
-**SpacesInConditionalStatement** (``Boolean``) :versionbadge:`clang-format 10` :ref:`¶ <SpacesInConditionalStatement>`
- If ``true``, spaces will be inserted around if/for/switch/while
+: If `true`, spaces will be inserted around if/for/switch/while
conditions.
- This option is **deprecated**. See ``InConditionalStatements`` of
- ``SpacesInParensOptions``.
+ This option is **deprecated**. See `InConditionalStatements` of
+ `SpacesInParensOptions`.
+
+(spacesincontainerliterals)=
-.. _SpacesInContainerLiterals:
+**SpacesInContainerLiterals** (`Boolean`) {versionbadge}`clang-format 3.7` {ref}`¶ <SpacesInContainerLiterals>`
-**SpacesInContainerLiterals** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpacesInContainerLiterals>`
- If ``true``, spaces are inserted inside container literals (e.g. ObjC and
+: If `true`, spaces are inserted inside container literals (e.g. ObjC and
Javascript array and dict literals). For JSON, use
- ``SpaceBeforeJsonColon`` instead.
+ `SpaceBeforeJsonColon` instead.
- .. code-block:: js
+ ```js
+ true: false:
+ var arr = [ 1, 2, 3 ]; vs. var arr = [1, 2, 3];
+ f({a : 1, b : 2, c : 3}); f({a: 1, b: 2, c: 3});
+ ```
- true: false:
- var arr = [ 1, 2, 3 ]; vs. var arr = [1, 2, 3];
- f({a : 1, b : 2, c : 3}); f({a: 1, b: 2, c: 3});
+(spacesinlinecommentprefix)=
-.. _SpacesInLineCommentPrefix:
+**SpacesInLineCommentPrefix** (`SpacesInLineComment`) {versionbadge}`clang-format 13` {ref}`¶ <SpacesInLineCommentPrefix>`
-**SpacesInLineCommentPrefix** (``SpacesInLineComment``) :versionbadge:`clang-format 13` :ref:`¶ <SpacesInLineCommentPrefix>`
- How many spaces are allowed at the start of a line comment. To disable the
- maximum set it to ``-1``, apart from that the maximum takes precedence
+: How many spaces are allowed at the start of a line comment. To disable the
+ maximum set it to `-1`, apart from that the maximum takes precedence
over the minimum.
- .. code-block:: c++
+ ```c++
+ Minimum = 1
+ Maximum = -1
+ // One space is forced
- Minimum = 1
- Maximum = -1
- // One space is forced
+ // but more spaces are possible
- // but more spaces are possible
-
- Minimum = 0
- Maximum = 0
- //Forces to start every comment directly after the slashes
+ Minimum = 0
+ Maximum = 0
+ //Forces to start every comment directly after the slashes
+ ```
Note that in line comment sections the relative indent of the subsequent
lines is kept, that means the following:
- .. code-block:: c++
-
- before: after:
- Minimum: 1
- //if (b) { // if (b) {
- // return true; // return true;
- //} // }
+ ```c++
+ before: after:
+ Minimum: 1
+ //if (b) { // if (b) {
+ // return true; // return true;
+ //} // }
- Maximum: 0
- /// List: ///List:
- /// - Foo /// - Foo
- /// - Bar /// - Bar
+ Maximum: 0
+ /// List: ///List:
+ /// - Foo /// - Foo
+ /// - Bar /// - Bar
+ ```
- This option has only effect if ``ReflowComments`` is set to ``true``.
+ This option has only effect if `ReflowComments` is set to `true`.
Nested configuration flags:
Control of spaces within a single line comment.
- * ``unsigned Minimum`` The minimum number of spaces at the start of the comment.
+ - `unsigned Minimum` The minimum number of spaces at the start of the comment.
- * ``unsigned Maximum`` The maximum number of spaces at the start of the comment.
+ - `unsigned Maximum` The maximum number of spaces at the start of the comment.
-.. _SpacesInParens:
+(spacesinparens)=
-**SpacesInParens** (``SpacesInParensStyle``) :versionbadge:`clang-format 17` :ref:`¶ <SpacesInParens>`
- Defines in which cases spaces will be inserted after ``(`` and before
- ``)``.
+**SpacesInParens** (`SpacesInParensStyle`) {versionbadge}`clang-format 17` {ref}`¶ <SpacesInParens>`
+
+: Defines in which cases spaces will be inserted after `(` and before
+ `)`.
Possible values:
- * ``SIPO_Never`` (in configuration: ``Never``)
+ - `SIPO_Never` (in configuration: `Never`)
Never put a space in parentheses.
- .. code-block:: c++
-
- void f() {
- if(true) {
- f();
- }
- }
+ ```c++
+ void f() {
+ if(true) {
+ f();
+ }
+ }
+ ```
- * ``SIPO_Custom`` (in configuration: ``Custom``)
+ - `SIPO_Custom` (in configuration: `Custom`)
Configure each individual space in parentheses in
`SpacesInParensOptions`.
-.. _SpacesInParensOptions:
+(spacesinparensoptions)=
-**SpacesInParensOptions** (``SpacesInParensCustom``) :versionbadge:`clang-format 17` :ref:`¶ <SpacesInParensOptions>`
- Control of individual spaces in parentheses.
+**SpacesInParensOptions** (`SpacesInParensCustom`) {versionbadge}`clang-format 17` {ref}`¶ <SpacesInParensOptions>`
- If ``SpacesInParens`` is set to ``Custom``, use this to specify
+: Control of individual spaces in parentheses.
+
+ If `SpacesInParens` is set to `Custom`, use this to specify
how each individual space in parentheses case should be handled.
Otherwise, this is ignored.
- .. code-block:: yaml
-
- # Example of usage:
- SpacesInParens: Custom
- SpacesInParensOptions:
- ExceptDoubleParentheses: false
- InConditionalStatements: true
- InEmptyParentheses: true
+ ```yaml
+ # Example of usage:
+ SpacesInParens: Custom
+ SpacesInParensOptions:
+ ExceptDoubleParentheses: false
+ InConditionalStatements: true
+ InEmptyParentheses: true
+ ```
Nested configuration flags:
Precise control over the spacing in parentheses.
- .. code-block:: c++
+ ```yaml
+ # Should be declared this way:
+ SpacesInParens: Custom
+ SpacesInParensOptions:
+ ExceptDoubleParentheses: false
+ InConditionalStatements: true
+ Other: true
+ ```
- # Should be declared this way:
- SpacesInParens: Custom
- SpacesInParensOptions:
- ExceptDoubleParentheses: false
- InConditionalStatements: true
- Other: true
-
- * ``bool ExceptDoubleParentheses`` Override any of the following options to prevent addition of space
+ - `bool ExceptDoubleParentheses` Override any of the following options to prevent addition of space
when both opening and closing parentheses use multiple parentheses.
- .. code-block:: c++
-
- true:
- __attribute__(( noreturn ))
- __decltype__(( x ))
- if (( a = b ))
+ ```c++
+ true:
+ __attribute__(( noreturn ))
+ __decltype__(( x ))
+ if (( a = b ))
false:
Uses the applicable option.
+ ```
- * ``bool InConditionalStatements`` Put a space in parentheses only inside conditional statements
- (``for/if/while/switch...``).
-
- .. code-block:: c++
- true: false:
- if ( a ) { ... } vs. if (a) { ... }
- while ( i < 5 ) { ... } while (i < 5) { ... }
+ - `bool InConditionalStatements` Put a space in parentheses only inside conditional statements
+ (`for/if/while/switch...`).
- * ``bool InCStyleCasts`` Put a space in C style casts.
+ ```c++
+ true: false:
+ if ( a ) { ... } vs. if (a) { ... }
+ while ( i < 5 ) { ... } while (i < 5) { ... }
+ ```
- .. code-block:: c++
+ - `bool InCStyleCasts` Put a space in C style casts.
- true: false:
- x = ( int32 )y vs. x = (int32)y
- y = (( int (*)(int) )foo)(x); y = ((int (*)(int))foo)(x);
+ ```c++
+ true: false:
+ x = ( int32 )y vs. x = (int32)y
+ y = (( int (*)(int) )foo)(x); y = ((int (*)(int))foo)(x);
+ ```
- * ``bool InEmptyParentheses`` Insert a space in empty parentheses, i.e. ``()``.
+ - `bool InEmptyParentheses` Insert a space in empty parentheses, i.e. `()`.
- .. code-block:: c++
+ ```c++
+ true: false:
+ void f( ) { vs. void f() {
+ int x[] = {foo( ), bar( )}; int x[] = {foo(), bar()};
+ if (true) { if (true) {
+ f( ); f();
+ } }
+ } }
+ ```
- true: false:
- void f( ) { vs. void f() {
- int x[] = {foo( ), bar( )}; int x[] = {foo(), bar()};
- if (true) { if (true) {
- f( ); f();
- } }
- } }
+ - `bool Other` Put a space in parentheses not covered by preceding options.
- * ``bool Other`` Put a space in parentheses not covered by preceding options.
+ ```c++
+ true: false:
+ t f( Deleted & ) & = delete; vs. t f(Deleted &) & = delete;
+ ```
- .. code-block:: c++
- true: false:
- t f( Deleted & ) & = delete; vs. t f(Deleted &) & = delete;
+(spacesinparentheses)=
+**SpacesInParentheses** (`Boolean`) {versionbadge}`clang-format 3.7` {ref}`¶ <SpacesInParentheses>`
-.. _SpacesInParentheses:
-
-**SpacesInParentheses** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpacesInParentheses>`
- If ``true``, spaces will be inserted after ``(`` and before ``)``.
+: If `true`, spaces will be inserted after `(` and before `)`.
This option is **deprecated**. The previous behavior is preserved by using
- ``SpacesInParens`` with ``Custom`` and by setting all
- ``SpacesInParensOptions`` to ``true`` except for ``InCStyleCasts`` and
- ``InEmptyParentheses``.
+ `SpacesInParens` with `Custom` and by setting all
+ `SpacesInParensOptions` to `true` except for `InCStyleCasts` and
+ `InEmptyParentheses`.
+
+(spacesinsquarebrackets)=
-.. _SpacesInSquareBrackets:
+**SpacesInSquareBrackets** (`Boolean`) {versionbadge}`clang-format 3.7` {ref}`¶ <SpacesInSquareBrackets>`
-**SpacesInSquareBrackets** (``Boolean``) :versionbadge:`clang-format 3.7` :ref:`¶ <SpacesInSquareBrackets>`
- If ``true``, spaces will be inserted after ``[`` and before ``]``.
+: If `true`, spaces will be inserted after `[` and before `]`.
Lambdas without arguments or unspecified size array declarations will not
be affected.
- .. code-block:: c++
+ ```c++
+ true: false:
+ int a[ 5 ]; vs. int a[5];
+ std::unique_ptr<int[]> foo() {} // Won't be affected
+ ```
- true: false:
- int a[ 5 ]; vs. int a[5];
- std::unique_ptr<int[]> foo() {} // Won't be affected
+(standard)=
-.. _Standard:
+**Standard** (`LanguageStandard`) {versionbadge}`clang-format 3.7` {ref}`¶ <Standard>`
-**Standard** (``LanguageStandard``) :versionbadge:`clang-format 3.7` :ref:`¶ <Standard>`
- Parse and format C++ constructs compatible with this standard.
+: Parse and format C++ constructs compatible with this standard.
- .. code-block:: c++
-
- c++03: latest:
- vector<set<int> > x; vs. vector<set<int>> x;
+ ```c++
+ c++03: latest:
+ vector<set<int> > x; vs. vector<set<int>> x;
+ ```
Possible values:
- * ``LS_Cpp03`` (in configuration: ``c++03``)
+ - `LS_Cpp03` (in configuration: `c++03`)
Parse and format as C++03.
- ``Cpp03`` is a deprecated alias for ``c++03``
+ `Cpp03` is a deprecated alias for `c++03`
- * ``LS_Cpp11`` (in configuration: ``c++11``)
+ - `LS_Cpp11` (in configuration: `c++11`)
Parse and format as C++11.
- * ``LS_Cpp14`` (in configuration: ``c++14``)
+ - `LS_Cpp14` (in configuration: `c++14`)
Parse and format as C++14.
- * ``LS_Cpp17`` (in configuration: ``c++17``)
+ - `LS_Cpp17` (in configuration: `c++17`)
Parse and format as C++17.
- * ``LS_Cpp20`` (in configuration: ``c++20``)
+ - `LS_Cpp20` (in configuration: `c++20`)
Parse and format as C++20.
- * ``LS_Cpp23`` (in configuration: ``c++23``)
+ - `LS_Cpp23` (in configuration: `c++23`)
Parse and format as C++23.
- * ``LS_Cpp26`` (in configuration: ``c++26``)
+ - `LS_Cpp26` (in configuration: `c++26`)
Parse and format as C++26.
- * ``LS_Latest`` (in configuration: ``Latest``)
+ - `LS_Latest` (in configuration: `Latest`)
Parse and format using the latest supported language version.
- ``Cpp11`` is a deprecated alias for ``Latest``
+ `Cpp11` is a deprecated alias for `Latest`
- * ``LS_Auto`` (in configuration: ``Auto``)
+ - `LS_Auto` (in configuration: `Auto`)
Automatic detection based on the input.
-.. _StatementAttributeLikeMacros:
+(statementattributelikemacros)=
+
+**StatementAttributeLikeMacros** (`List of Strings`) {versionbadge}`clang-format 12` {ref}`¶ <StatementAttributeLikeMacros>`
-**StatementAttributeLikeMacros** (``List of Strings``) :versionbadge:`clang-format 12` :ref:`¶ <StatementAttributeLikeMacros>`
- Macros which are ignored in front of a statement, as if they were an
+: Macros which are ignored in front of a statement, as if they were an
attribute. So that they are not parsed as identifier, for example for Qts
emit.
- .. code-block:: c++
+ ```c++
+ AlignConsecutiveDeclarations: true
+ StatementAttributeLikeMacros: []
+ unsigned char data = 'x';
+ emit signal(data); // This is parsed as variable declaration.
- AlignConsecutiveDeclarations: true
- StatementAttributeLikeMacros: []
- unsigned char data = 'x';
- emit signal(data); // This is parsed as variable declaration.
+ AlignConsecutiveDeclarations: true
+ StatementAttributeLikeMacros: [emit]
+ unsigned char data = 'x';
+ emit signal(data); // Now it's fine again.
+ ```
- AlignConsecutiveDeclarations: true
- StatementAttributeLikeMacros: [emit]
- unsigned char data = 'x';
- emit signal(data); // Now it's fine again.
+(statementmacros)=
-.. _StatementMacros:
+**StatementMacros** (`List of Strings`) {versionbadge}`clang-format 8` {ref}`¶ <StatementMacros>`
-**StatementMacros** (``List of Strings``) :versionbadge:`clang-format 8` :ref:`¶ <StatementMacros>`
- A vector of macros that should be interpreted as complete statements.
+: A vector of macros that should be interpreted as complete statements.
Typical macros are expressions and require a semicolon to be added.
Sometimes this is not the case, and this allows to make clang-format aware
@@ -7706,50 +7876,53 @@ the configuration (without a prefix: ``Auto``).
For example: Q_UNUSED
-.. _TabWidth:
+(tabwidth)=
-**TabWidth** (``Unsigned``) :versionbadge:`clang-format 3.7` :ref:`¶ <TabWidth>`
- The number of columns used for tab stops.
+**TabWidth** (`Unsigned`) {versionbadge}`clang-format 3.7` {ref}`¶ <TabWidth>`
-.. _TableGenBreakInsideDAGArg:
+: The number of columns used for tab stops.
-**TableGenBreakInsideDAGArg** (``DAGArgStyle``) :versionbadge:`clang-format 19` :ref:`¶ <TableGenBreakInsideDAGArg>`
- The styles of the line break inside the DAGArg in TableGen.
+(tablegenbreakinsidedagarg)=
+
+**TableGenBreakInsideDAGArg** (`DAGArgStyle`) {versionbadge}`clang-format 19` {ref}`¶ <TableGenBreakInsideDAGArg>`
+
+: The styles of the line break inside the DAGArg in TableGen.
Possible values:
- * ``DAS_DontBreak`` (in configuration: ``DontBreak``)
+ - `DAS_DontBreak` (in configuration: `DontBreak`)
Never break inside DAGArg.
- .. code-block:: c++
+ ```c++
+ let DAGArgIns = (ins i32:$src1, i32:$src2);
+ ```
- let DAGArgIns = (ins i32:$src1, i32:$src2);
-
- * ``DAS_BreakElements`` (in configuration: ``BreakElements``)
+ - `DAS_BreakElements` (in configuration: `BreakElements`)
Break inside DAGArg after each list element but for the last.
This aligns to the first element.
- .. code-block:: c++
-
- let DAGArgIns = (ins i32:$src1,
- i32:$src2);
+ ```c++
+ let DAGArgIns = (ins i32:$src1,
+ i32:$src2);
+ ```
- * ``DAS_BreakAll`` (in configuration: ``BreakAll``)
+ - `DAS_BreakAll` (in configuration: `BreakAll`)
Break inside DAGArg after the operator and the all elements.
- .. code-block:: c++
+ ```c++
+ let DAGArgIns = (ins
+ i32:$src1,
+ i32:$src2
+ );
+ ```
- let DAGArgIns = (ins
- i32:$src1,
- i32:$src2
- );
+(tablegenbreakingdagargoperators)=
-.. _TableGenBreakingDAGArgOperators:
+**TableGenBreakingDAGArgOperators** (`List of Strings`) {versionbadge}`clang-format 19` {ref}`¶ <TableGenBreakingDAGArgOperators>`
-**TableGenBreakingDAGArgOperators** (``List of Strings``) :versionbadge:`clang-format 19` :ref:`¶ <TableGenBreakingDAGArgOperators>`
- Works only when TableGenBreakInsideDAGArg is not DontBreak.
+: Works only when TableGenBreakInsideDAGArg is not DontBreak.
The string list needs to consist of identifiers in TableGen.
If any identifier is specified, this limits the line breaks by
TableGenBreakInsideDAGArg option only on DAGArg values beginning with
@@ -7757,183 +7930,190 @@ the configuration (without a prefix: ``Auto``).
For example the configuration,
- .. code-block:: yaml
-
- TableGenBreakInsideDAGArg: BreakAll
- TableGenBreakingDAGArgOperators: [ins, outs]
+ ```yaml
+ TableGenBreakInsideDAGArg: BreakAll
+ TableGenBreakingDAGArgOperators: [ins, outs]
+ ```
makes the line break only occurs inside DAGArgs beginning with the
- specified identifiers ``ins`` and ``outs``.
-
+ specified identifiers `ins` and `outs`.
- .. code-block:: c++
+ ```c++
+ let DAGArgIns = (ins
+ i32:$src1,
+ i32:$src2
+ );
+ let DAGArgOtherID = (other i32:$other1, i32:$other2);
+ let DAGArgBang = (!cast<SomeType>("Some") i32:$src1, i32:$src2)
+ ```
- let DAGArgIns = (ins
- i32:$src1,
- i32:$src2
- );
- let DAGArgOtherID = (other i32:$other1, i32:$other2);
- let DAGArgBang = (!cast<SomeType>("Some") i32:$src1, i32:$src2)
+(templatenames)=
-.. _TemplateNames:
+**TemplateNames** (`List of Strings`) {versionbadge}`clang-format 20` {ref}`¶ <TemplateNames>`
-**TemplateNames** (``List of Strings``) :versionbadge:`clang-format 20` :ref:`¶ <TemplateNames>`
- A vector of non-keyword identifiers that should be interpreted as template
+: A vector of non-keyword identifiers that should be interpreted as template
names.
- A ``<`` after a template name is annotated as a template opener instead of
+ A `<` after a template name is annotated as a template opener instead of
a binary operator.
-.. _TypeNames:
+(typenames)=
-**TypeNames** (``List of Strings``) :versionbadge:`clang-format 17` :ref:`¶ <TypeNames>`
- A vector of non-keyword identifiers that should be interpreted as type
+**TypeNames** (`List of Strings`) {versionbadge}`clang-format 17` {ref}`¶ <TypeNames>`
+
+: A vector of non-keyword identifiers that should be interpreted as type
names.
- A ``*``, ``&``, or ``&&`` between a type name and another non-keyword
+ A `*`, `&`, or `&&` between a type name and another non-keyword
identifier is annotated as a pointer or reference token instead of a
binary operator.
-.. _TypenameMacros:
+(typenamemacros)=
+
+**TypenameMacros** (`List of Strings`) {versionbadge}`clang-format 9` {ref}`¶ <TypenameMacros>`
-**TypenameMacros** (``List of Strings``) :versionbadge:`clang-format 9` :ref:`¶ <TypenameMacros>`
- A vector of macros that should be interpreted as type declarations instead
+: A vector of macros that should be interpreted as type declarations instead
of as function calls.
These are expected to be macros of the form:
- .. code-block:: c++
-
- STACK_OF(...)
+ ```c++
+ STACK_OF(...)
+ ```
In the .clang-format configuration file, this can be configured like:
- .. code-block:: yaml
-
- TypenameMacros: [STACK_OF, LIST]
+ ```yaml
+ TypenameMacros: [STACK_OF, LIST]
+ ```
For example: OpenSSL STACK_OF, BSD LIST_ENTRY.
-.. _UseCRLF:
+(usecrlf)=
+
+**UseCRLF** (`Boolean`) {versionbadge}`clang-format 10` {ref}`¶ <UseCRLF>`
+
+: This option is **deprecated**. See `LF` and `CRLF` of `LineEnding`.
-**UseCRLF** (``Boolean``) :versionbadge:`clang-format 10` :ref:`¶ <UseCRLF>`
- This option is **deprecated**. See ``LF`` and ``CRLF`` of ``LineEnding``.
+(usetab)=
-.. _UseTab:
+**UseTab** (`UseTabStyle`) {versionbadge}`clang-format 3.7` {ref}`¶ <UseTab>`
-**UseTab** (``UseTabStyle``) :versionbadge:`clang-format 3.7` :ref:`¶ <UseTab>`
- The way to use tab characters in the resulting file.
+: The way to use tab characters in the resulting file.
Possible values:
- * ``UT_Never`` (in configuration: ``Never``)
+ - `UT_Never` (in configuration: `Never`)
Never use tab.
- * ``UT_ForIndentation`` (in configuration: ``ForIndentation``)
+ - `UT_ForIndentation` (in configuration: `ForIndentation`)
Use tabs only for indentation.
- * ``UT_ForContinuationAndIndentation`` (in configuration: ``ForContinuationAndIndentation``)
+ - `UT_ForContinuationAndIndentation` (in configuration: `ForContinuationAndIndentation`)
Fill all leading whitespace with tabs, and use spaces for alignment that
appears within a line (e.g. consecutive assignments and declarations).
- * ``UT_AlignWithSpaces`` (in configuration: ``AlignWithSpaces``)
+ - `UT_AlignWithSpaces` (in configuration: `AlignWithSpaces`)
Use tabs for line continuation and indentation, and spaces for
alignment.
- * ``UT_Always`` (in configuration: ``Always``)
+ - `UT_Always` (in configuration: `Always`)
Use tabs whenever we need to fill whitespace that spans at least from
one tab stop to the next one.
-.. _VariableTemplates:
+(variabletemplates)=
-**VariableTemplates** (``List of Strings``) :versionbadge:`clang-format 20` :ref:`¶ <VariableTemplates>`
- A vector of non-keyword identifiers that should be interpreted as variable
+**VariableTemplates** (`List of Strings`) {versionbadge}`clang-format 20` {ref}`¶ <VariableTemplates>`
+
+: A vector of non-keyword identifiers that should be interpreted as variable
template names.
- A ``)`` after a variable template instantiation is **not** annotated as
+ A `)` after a variable template instantiation is **not** annotated as
the closing parenthesis of C-style cast operator.
-.. _VerilogBreakBetweenInstancePorts:
+(verilogbreakbetweeninstanceports)=
-**VerilogBreakBetweenInstancePorts** (``Boolean``) :versionbadge:`clang-format 17` :ref:`¶ <VerilogBreakBetweenInstancePorts>`
- For Verilog, put each port on its own line in module instantiations.
+**VerilogBreakBetweenInstancePorts** (`Boolean`) {versionbadge}`clang-format 17` {ref}`¶ <VerilogBreakBetweenInstancePorts>`
- .. code-block:: c++
+: For Verilog, put each port on its own line in module instantiations.
- true:
- ffnand ff1(.q(),
- .qbar(out1),
- .clear(in1),
- .preset(in2));
+ ```c++
+ true:
+ ffnand ff1(.q(),
+ .qbar(out1),
+ .clear(in1),
+ .preset(in2));
- false:
- ffnand ff1(.q(), .qbar(out1), .clear(in1), .preset(in2));
+ false:
+ ffnand ff1(.q(), .qbar(out1), .clear(in1), .preset(in2));
+ ```
-.. _WhitespaceSensitiveMacros:
+(whitespacesensitivemacros)=
-**WhitespaceSensitiveMacros** (``List of Strings``) :versionbadge:`clang-format 11` :ref:`¶ <WhitespaceSensitiveMacros>`
- A vector of macros which are whitespace-sensitive and should not
+**WhitespaceSensitiveMacros** (`List of Strings`) {versionbadge}`clang-format 11` {ref}`¶ <WhitespaceSensitiveMacros>`
+
+: A vector of macros which are whitespace-sensitive and should not
be touched.
These are expected to be macros of the form:
- .. code-block:: c++
-
- STRINGIZE(...)
+ ```c++
+ STRINGIZE(...)
+ ```
In the .clang-format configuration file, this can be configured like:
- .. code-block:: yaml
-
- WhitespaceSensitiveMacros: [STRINGIZE, PP_STRINGIZE]
+ ```yaml
+ WhitespaceSensitiveMacros: [STRINGIZE, PP_STRINGIZE]
+ ```
For example: BOOST_PP_STRINGIZE
-.. _WrapNamespaceBodyWithEmptyLines:
+(wrapnamespacebodywithemptylines)=
+
+**WrapNamespaceBodyWithEmptyLines** (`WrapNamespaceBodyWithEmptyLinesStyle`) {versionbadge}`clang-format 20` {ref}`¶ <WrapNamespaceBodyWithEmptyLines>`
-**WrapNamespaceBodyWithEmptyLines** (``WrapNamespaceBodyWithEmptyLinesStyle``) :versionbadge:`clang-format 20` :ref:`¶ <WrapNamespaceBodyWithEmptyLines>`
- Wrap namespace body with empty lines.
+: Wrap namespace body with empty lines.
Possible values:
- * ``WNBWELS_Never`` (in configuration: ``Never``)
+ - `WNBWELS_Never` (in configuration: `Never`)
Remove all empty lines at the beginning and the end of namespace body.
- .. code-block:: c++
-
- namespace N1 {
- namespace N2 {
- function();
- }
- }
+ ```c++
+ namespace N1 {
+ namespace N2 {
+ function();
+ }
+ }
+ ```
- * ``WNBWELS_Always`` (in configuration: ``Always``)
+ - `WNBWELS_Always` (in configuration: `Always`)
Always have at least one empty line at the beginning and the end of
namespace body except that the number of empty lines between consecutive
nested namespace definitions is not increased.
- .. code-block:: c++
-
- namespace N1 {
- namespace N2 {
+ ```c++
+ namespace N1 {
+ namespace N2 {
- function();
+ function();
- }
- }
+ }
+ }
+ ```
- * ``WNBWELS_Leave`` (in configuration: ``Leave``)
+ - `WNBWELS_Leave` (in configuration: `Leave`)
Keep existing newlines at the beginning and the end of namespace body.
- ``MaxEmptyLinesToKeep`` still applies.
+ `MaxEmptyLinesToKeep` still applies.
-.. END_FORMAT_STYLE_OPTIONS
+% END_FORMAT_STYLE_OPTIONS
-Adding additional style options
-===============================
+## Adding additional style options
Each additional style option adds costs to the clang-format project. Some of
these costs affect the clang-format development itself, as we need to make
@@ -7948,96 +8128,94 @@ used by a codebase somewhere in the wild. Of course, we do want to support all
major projects and thus have established the following bar for adding style
options. Each new style option must:
- * be used in a project of significant size (have dozens of contributors)
- * have a publicly accessible style guide
- * have a person willing to contribute and maintain patches
+> - be used in a project of significant size (have dozens of contributors)
+> - have a publicly accessible style guide
+> - have a person willing to contribute and maintain patches
-Examples
-========
+## Examples
-A style similar to the `Linux Kernel style
-<https://www.kernel.org/doc/html/latest/process/coding-style.html>`_:
+A style similar to the [Linux Kernel style](https://www.kernel.org/doc/html/latest/process/coding-style.html):
-.. code-block:: yaml
-
- BasedOnStyle: LLVM
- IndentWidth: 8
- UseTab: Always
- BreakBeforeBraces: Linux
- AllowShortIfStatementsOnASingleLine: false
- IndentCaseLabels: false
+```yaml
+BasedOnStyle: LLVM
+IndentWidth: 8
+UseTab: Always
+BreakBeforeBraces: Linux
+AllowShortIfStatementsOnASingleLine: false
+IndentCaseLabels: false
+```
The result is (imagine that tabs are used for indentation here):
-.. code-block:: c++
+```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_
diff erent();
- void test()
- {
- switch (x) {
- case 0:
- case 1:
- do_something();
- break;
- case 2:
- do_something_else();
- break;
- default:
- break;
- }
- if (condition)
- do_something_completely_
diff erent();
-
- if (x == y) {
- q();
- } else if (x > y) {
- w();
- } else {
- r();
- }
- }
+ 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: Never
- IndentWidth: 4
- BreakBeforeBraces: Allman
- AllowShortIfStatementsOnASingleLine: false
- IndentCaseLabels: false
- ColumnLimit: 0
+```yaml
+UseTab: Never
+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_something_completely_
diff erent();
+```c++
+void test()
+{
+ switch (suffix)
+ {
+ case 0:
+ case 1:
+ do_something();
+ break;
+ case 2:
+ do_something_else();
+ break;
+ default:
+ break;
+ }
+ if (condition)
+ do_something_completely_
diff erent();
- if (x == y)
- {
- q();
- }
- else if (x > y)
- {
- w();
- }
- else
- {
- r();
- }
- }
+ if (x == y)
+ {
+ q();
+ }
+ else if (x > y)
+ {
+ w();
+ }
+ else
+ {
+ r();
+ }
+}
+```
diff --git a/clang/docs/tools/dump_format_help.py b/clang/docs/tools/dump_format_help.py
index 7ef22dcad3a13..a733c344c3bdd 100755
--- a/clang/docs/tools/dump_format_help.py
+++ b/clang/docs/tools/dump_format_help.py
@@ -13,8 +13,8 @@
def substitute(text, tag, contents):
- replacement = "\n.. START_%s\n\n%s\n\n.. END_%s\n" % (tag, contents, tag)
- pattern = r"\n\.\. START_%s\n.*\n\.\. END_%s\n" % (tag, tag)
+ replacement = f"\n% START_{tag}\n\n{contents}\n\n% END_{tag}\n"
+ pattern = rf"\n% START_{tag}\n.*\n% END_{tag}\n"
return re.sub(pattern, replacement, text, flags=re.S)
@@ -38,15 +38,7 @@ def get_help_text():
out = get_help_output()
out = re.sub(r" clang-format\.exe ", " clang-format ", out)
- out = (
- """.. code-block:: console
-
-$ clang-format --help
-"""
- + out
- )
- out = indent(out, 2, indent_first_line=False)
- return out
+ return "```console\n$ clang-format --help\n" + out + "```"
def validate(text, columns):
diff --git a/clang/docs/tools/dump_format_style.py b/clang/docs/tools/dump_format_style.py
index a78c8f54045cc..c18c70daf9f4c 100755
--- a/clang/docs/tools/dump_format_style.py
+++ b/clang/docs/tools/dump_format_style.py
@@ -8,6 +8,7 @@
import os
import re
import sys
+import textwrap
from io import TextIOWrapper
from typing import Set
@@ -27,9 +28,9 @@
def substitute(text, tag, contents):
- replacement = "\n.. START_%s\n\n%s\n\n.. END_%s\n" % (tag, contents, tag)
- pattern = r"\n\.\. START_%s\n.*\n\.\. END_%s\n" % (tag, tag)
- return re.sub(pattern, "%s", text, flags=re.S) % replacement
+ replacement = f"\n% START_{tag}\n\n{contents}\n\n% END_{tag}\n"
+ pattern = rf"\n% START_{tag}\n.*\n% END_{tag}\n"
+ return re.sub(pattern, lambda _: replacement, text, flags=re.S)
def register_plural(singular: str, plural: str):
@@ -70,6 +71,57 @@ def pluralize(word: str):
return register_plural(word, word + "s")
+def reindent_fenced_blocks(text):
+ """Reindent fenced block body text to match the fence nesting indent.
+
+ For example, this collapses the code body's internal Doxygen indentation:
+
+ ```yaml
+ BasedOnStyle: LLVM
+ ```
+
+ to this Markdown shape:
+
+ ```yaml
+ BasedOnStyle: LLVM
+ ```
+
+ It also normalizes MyST colon-fenced directives:
+
+ :::{note}
+ This line should use the directive's indentation.
+ :::
+
+ to this Markdown shape:
+
+ :::{note}
+ This line should use the directive's indentation.
+ :::
+ """
+
+ def reindent_block(match):
+ indent = match.group("indent")
+ fence = match.group("fence")
+ info = match.group("info")
+ body = match.group("body")
+ dedented_body = "".join(
+ (indent + line if line.strip() else line)
+ for line in textwrap.dedent(body).splitlines(keepends=True)
+ )
+ return (
+ f"{indent}{fence}{info}\n"
+ f"{dedented_body}"
+ f"{indent}{fence}{match.group('trailing')}"
+ )
+
+ return re.sub(
+ r"(?ms)^(?P<indent>[^\S\n]*)(?P<fence>```|:::)(?P<info>[^\n]*)\n"
+ r"(?P<body>.*?)(?P=indent)(?P=fence)(?P<trailing>\n|$)",
+ reindent_block,
+ text,
+ )
+
+
def to_yaml_type(typestr: str):
if typestr == "bool":
return "Boolean"
@@ -93,13 +145,39 @@ def to_yaml_type(typestr: str):
return typestr
-def doxygen2rst(text):
- text = re.sub(r"<tt>\s*(.*?)\s*<\/tt>", r"``\1``", text)
- text = re.sub(r"\\c ([^ ,;\.]+)", r"``\1``", text)
+def doxygen2md(text):
+ text = re.sub(r"<tt>\s*(.*?)\s*<\/tt>", r"`\1`", text)
+ text = re.sub(r"\\c ([^ ,;\.]+)", r"`\1`", text)
+ text = re.sub(r"(?m)^(\s*)\* ", r"\1- ", text)
text = re.sub(r"\\\w+ ", "", text)
+ text = re.sub(
+ r"(?ms)^(?P<indent>[^\S\n]*)```(?P<lang>[^\n]*)\n"
+ r"(?P<body>.*?)(?P=indent)```\n"
+ r"(?P<rest>(?P=indent) false:\n(?:(?P=indent) .*(?:\n|$))+)",
+ lambda match: (
+ f"{match.group('indent')}```{match.group('lang')}\n"
+ f"{match.group('body')}{match.group('rest').rstrip()}\n"
+ f"{match.group('indent')}```\n"
+ ),
+ text,
+ )
+ text = reindent_fenced_blocks(text)
+ # Ensure a blank line before opening fences for proper Markdown loose-list rendering.
+ # Opening ``` fences have a lang word; opening ::: fences have {. Closing fences
+ # have neither, so they are unaffected.
+ text = re.sub(r"([^\n])\n([ \t]*(?:```\w|:::\{))", r"\1\n\n\2", text)
return text
+def definition_body(text):
+ lines = doxygen2md(text.strip()).splitlines()
+ if not lines:
+ return ":"
+ result = [": " + lines[0]]
+ result.extend((" " + line) if line else "" for line in lines[1:])
+ return "\n".join(result)
+
+
def indent(text, columns, indent_first_line=True):
indent_str = " " * columns
s = re.sub(r"\n([^\n])", "\n" + indent_str + "\\1", text, flags=re.S)
@@ -118,14 +196,14 @@ def __init__(self, name, opt_type, comment, version):
self.version = version
def __str__(self):
- s = ".. _%s:\n\n**%s** (``%s``) " % (
- self.name,
+ s = "(%s)=\n\n**%s** (`%s`) " % (
+ self.name.lower(),
self.name,
to_yaml_type(self.type),
)
if self.version:
- s += ":versionbadge:`clang-format %s` " % self.version
- s += ":ref:`¶ <%s>`\n%s" % (self.name, doxygen2rst(indent(self.comment, 2)))
+ s += "{versionbadge}`clang-format %s` " % self.version
+ s += "{ref}`¶ <%s>`\n\n%s" % (self.name, definition_body(self.comment))
if self.enum and self.enum.values:
s += indent("\n\nPossible values:\n\n%s\n" % self.enum, 2)
if self.nested_struct:
@@ -143,7 +221,7 @@ def __init__(self, name, comment):
self.values = []
def __str__(self):
- return self.comment + "\n" + "\n".join(map(str, self.values))
+ return doxygen2md(self.comment) + "\n" + "\n".join(map(str, self.values))
class NestedField(object):
@@ -154,14 +232,14 @@ def __init__(self, name, comment, version):
def __str__(self):
if self.version:
- return "\n* ``%s`` :versionbadge:`clang-format %s` %s" % (
+ return "\n- `%s` {versionbadge}`clang-format %s` %s" % (
self.name,
self.version,
- doxygen2rst(indent(self.comment, 2, indent_first_line=False)),
+ doxygen2md(indent(self.comment, 2, indent_first_line=False)),
)
- return "\n* ``%s`` %s" % (
+ return "\n- `%s` %s" % (
self.name,
- doxygen2rst(indent(self.comment, 2, indent_first_line=False)),
+ doxygen2md(indent(self.comment, 2, indent_first_line=False)),
)
@@ -186,17 +264,17 @@ def __init__(self, name, enumtype, comment, version, values):
def __str__(self):
s = ""
if self.version:
- s = "\n* ``%s %s`` :versionbadge:`clang-format %s`\n\n%s" % (
+ s = "\n- `%s %s` {versionbadge}`clang-format %s`\n\n%s" % (
to_yaml_type(self.type),
self.name,
self.version,
- doxygen2rst(indent(self.comment, 2)),
+ doxygen2md(indent(self.comment, 2)),
)
else:
- s = "\n* ``%s %s``\n%s" % (
+ s = "\n- `%s %s`\n%s" % (
to_yaml_type(self.type),
self.name,
- doxygen2rst(indent(self.comment, 2)),
+ doxygen2md(indent(self.comment, 2)),
)
s += indent("\nPossible values:\n\n", 2)
s += indent("\n".join(map(str, self.values)), 2)
@@ -210,10 +288,10 @@ def __init__(self, name, comment, config):
self.config = config
def __str__(self):
- return "* ``%s`` (in configuration: ``%s``)\n%s" % (
+ return "- `%s` (in configuration: `%s`)\n%s" % (
self.name,
re.sub(".*_", "", self.config),
- doxygen2rst(indent(self.comment, 2)),
+ doxygen2md(indent(self.comment, 2)),
)
@@ -248,7 +326,7 @@ def __clean_comment_line(self, line: str):
lang = match.group("lang")
if not lang:
lang = "c++"
- return f"\n{indent_str}.. code-block:: {lang}\n\n"
+ return f"{indent_str}```{lang}\n"
endcode_match = re.match(r"^/// +\\endcode$", line)
if endcode_match:
@@ -257,7 +335,7 @@ def __clean_comment_line(self, line: str):
"no correct `\\code` found before this `\\endcode`", line
)
self.in_code_block = False
- return ""
+ return " " * self.code_indent + "```\n"
# check code block indentation
if (
@@ -270,22 +348,26 @@ def __clean_comment_line(self, line: str):
else:
self.__warning("code block should be indented", line)
self.last_err_lineno = self.lineno
+ if self.in_code_block:
+ if line == "///":
+ return "\n"
+ return " " * self.code_indent + line[6 + self.code_indent :] + "\n"
match = re.match(r"^/// \\warning$", line)
if match:
- return "\n.. warning::\n\n"
+ return ":::{warning}\n"
endwarning_match = re.match(r"^/// +\\endwarning$", line)
if endwarning_match:
- return ""
+ return ":::\n"
match = re.match(r"^/// \\note$", line)
if match:
- return "\n.. note::\n\n"
+ return ":::{note}\n"
endnote_match = re.match(r"^/// +\\endnote$", line)
if endnote_match:
- return ""
+ return ":::\n"
return line[4:] + "\n"
def read_options(self):
diff --git a/clang/include/clang/Format/Format.h b/clang/include/clang/Format/Format.h
index 540a50047696a..3948337d2fc3d 100644
--- a/clang/include/clang/Format/Format.h
+++ b/clang/include/clang/Format/Format.h
@@ -51,7 +51,7 @@ class ParseErrorCategory final : public std::error_category {
const std::error_category &getParseCategory();
std::error_code make_error_code(ParseError e);
-/// The ``FormatStyle`` is used to configure the formatting to follow
+/// The `FormatStyle` is used to configure the formatting to follow
/// specific guidelines.
struct FormatStyle {
// If the BasedOn: was InheritParentConfig and this style needs the file from
@@ -59,11 +59,11 @@ struct FormatStyle {
// Thus the // instead of ///.
std::string InheritConfig;
- /// The extra indent or outdent of access modifiers, e.g. ``public:``.
+ /// The extra indent or outdent of access modifiers, e.g. `public:`.
/// \version 3.3
int AccessModifierOffset;
- /// If ``true``, horizontally aligns arguments after an open bracket.
+ /// If `true`, horizontally aligns arguments after an open bracket.
///
/// \code
/// true: vs. false
@@ -73,12 +73,12 @@ struct FormatStyle {
///
/// \note
/// As of clang-format 22 this option is a bool with the previous
- /// option of ``Align`` replaced with ``true``, ``DontAlign`` replaced
- /// with ``false``, and the options of ``AlwaysBreak`` and ``BlockIndent``
- /// replaced with ``true`` and with setting of new style options using
- /// ``BreakAfterOpenBracketBracedList``, ``BreakAfterOpenBracketFunction``,
- /// ``BreakAfterOpenBracketIf``, ``BreakBeforeCloseBracketBracedList``,
- /// ``BreakBeforeCloseBracketFunction``, and ``BreakBeforeCloseBracketIf``.
+ /// option of `Align` replaced with `true`, `DontAlign` replaced
+ /// with `false`, and the options of `AlwaysBreak` and `BlockIndent`
+ /// replaced with `true` and with setting of new style options using
+ /// `BreakAfterOpenBracketBracedList`, `BreakAfterOpenBracketFunction`,
+ /// `BreakAfterOpenBracketIf`, `BreakBeforeCloseBracketBracedList`,
+ /// `BreakBeforeCloseBracketFunction`, and `BreakBeforeCloseBracketIf`.
/// \endnote
///
/// This applies to round brackets (parentheses), angle brackets and square
@@ -111,7 +111,7 @@ struct FormatStyle {
/// Don't align array initializer columns.
AIAS_None
};
- /// If not ``None``, when using initialization for an array of structs
+ /// If not `None`, when using initialization for an array of structs
/// aligns the fields into columns.
///
/// \note
@@ -126,11 +126,11 @@ struct FormatStyle {
///
/// They can also be read as a whole for compatibility. The choices are:
///
- /// * ``None``
- /// * ``Consecutive``
- /// * ``AcrossEmptyLines``
- /// * ``AcrossComments``
- /// * ``AcrossEmptyLinesAndComments``
+ /// * `None`
+ /// * `Consecutive`
+ /// * `AcrossEmptyLines`
+ /// * `AcrossComments`
+ /// * `AcrossEmptyLinesAndComments`
///
/// For example, to align across empty lines and not across comments, either
/// of these work.
@@ -194,8 +194,8 @@ struct FormatStyle {
/// double e = 4;
/// \endcode
bool AcrossComments;
- /// Only for ``AlignConsecutiveAssignments``. Whether compound assignments
- /// like ``+=`` are aligned along with ``=``.
+ /// Only for `AlignConsecutiveAssignments`. Whether compound assignments
+ /// like `+=` are aligned along with `=`.
/// \code
/// true:
/// a &= 2;
@@ -206,7 +206,7 @@ struct FormatStyle {
/// bbb = 2;
/// \endcode
bool AlignCompound;
- /// Only for ``AlignConsecutiveDeclarations``. Whether function declarations
+ /// Only for `AlignConsecutiveDeclarations`. Whether function declarations
/// are aligned.
/// \code
/// true:
@@ -220,7 +220,7 @@ struct FormatStyle {
/// size_t f3(void);
/// \endcode
bool AlignFunctionDeclarations;
- /// Only for ``AlignConsecutiveDeclarations``. Whether function pointers are
+ /// Only for `AlignConsecutiveDeclarations`. Whether function pointers are
/// aligned.
/// \code
/// true:
@@ -236,12 +236,12 @@ struct FormatStyle {
/// int (*f)();
/// \endcode
bool AlignFunctionPointers;
- /// Only for ``AlignConsecutiveAssignments``.
- /// Whether enum assignments are aligned. If ``Enabled`` is ``false``,
- /// setting this to ``true`` forces alignment for enum assignments only.
- /// If ``Enabled`` is ``true``, enum assignments are always aligned.
+ /// Only for `AlignConsecutiveAssignments`.
+ /// Whether enum assignments are aligned. If `Enabled` is `false`,
+ /// setting this to `true` forces alignment for enum assignments only.
+ /// If `Enabled` is `true`, enum assignments are always aligned.
bool EnumAssignments;
- /// Only for ``AlignConsecutiveAssignments``. Whether short assignment
+ /// Only for `AlignConsecutiveAssignments`. Whether short assignment
/// operators are left-padded to the same length as long ones in order to
/// put all assignment operators to the right of the left hand side.
/// \code
@@ -276,7 +276,7 @@ struct FormatStyle {
/// Style of aligning consecutive assignments.
///
- /// ``Consecutive`` will result in formattings like:
+ /// `Consecutive` will result in formattings like:
/// \code
/// int a = 1;
/// int somelongname = 2;
@@ -287,7 +287,7 @@ struct FormatStyle {
/// Style of aligning consecutive bit fields.
///
- /// ``Consecutive`` will align the bitfield separators of consecutive lines.
+ /// `Consecutive` will align the bitfield separators of consecutive lines.
/// This will result in formattings like:
/// \code
/// int aaaa : 1;
@@ -299,7 +299,7 @@ struct FormatStyle {
/// Style of aligning consecutive declarations.
///
- /// ``Consecutive`` will align the declaration names of consecutive lines.
+ /// `Consecutive` will align the declaration names of consecutive lines.
/// This will result in formattings like:
/// \code
/// int aaaa = 12;
@@ -311,7 +311,7 @@ struct FormatStyle {
/// Style of aligning consecutive macro definitions.
///
- /// ``Consecutive`` will result in formattings like:
+ /// `Consecutive` will result in formattings like:
/// \code
/// #define SHORT_NAME 42
/// #define LONGER_NAME 0x007f
@@ -424,8 +424,8 @@ struct FormatStyle {
};
/// Style of aligning consecutive short case labels.
- /// Only applies if ``AllowShortCaseExpressionOnASingleLine`` or
- /// ``AllowShortCaseLabelsOnASingleLine`` is ``true``.
+ /// Only applies if `AllowShortCaseExpressionOnASingleLine` or
+ /// `AllowShortCaseLabelsOnASingleLine` is `true`.
///
/// \code{.yaml}
/// # Example of usage:
@@ -517,7 +517,7 @@ struct FormatStyle {
/// Different styles for aligning operands.
enum OperandAlignmentStyle : int8_t {
/// Do not align operands of binary and ternary expressions.
- /// The wrapped lines are indented ``ContinuationIndentWidth`` spaces from
+ /// The wrapped lines are indented `ContinuationIndentWidth` spaces from
/// the start of the line.
OAS_DontAlign,
/// Horizontally align operands of binary and ternary expressions.
@@ -529,7 +529,7 @@ struct FormatStyle {
/// ccccccccccccccc;
/// \endcode
///
- /// When ``BreakBeforeBinaryOperators`` is set, the wrapped operator is
+ /// When `BreakBeforeBinaryOperators` is set, the wrapped operator is
/// aligned with the operand on the first line.
/// \code
/// int aaa = bbbbbbbbbbbbbbb
@@ -538,8 +538,8 @@ struct FormatStyle {
OAS_Align,
/// Horizontally align operands of binary and ternary expressions.
///
- /// This is similar to ``OAS_Align``, except when
- /// ``BreakBeforeBinaryOperators`` is set, the operator is un-indented so
+ /// This is similar to `OAS_Align`, except when
+ /// `BreakBeforeBinaryOperators` is set, the operator is un-indented so
/// that the wrapped operand is aligned with the operand on the first line.
/// \code
/// int aaa = bbbbbbbbbbbbbbb
@@ -548,7 +548,7 @@ struct FormatStyle {
OAS_AlignAfterOperator,
};
- /// If ``true``, horizontally align operands of binary and ternary
+ /// If `true`, horizontally align operands of binary and ternary
/// expressions.
/// \version 3.5
OperandAlignmentStyle AlignOperands;
@@ -589,7 +589,7 @@ struct FormatStyle {
/// Specifies the way to align trailing comments.
TrailingCommentsAlignmentKinds Kind;
/// How many empty lines to apply alignment.
- /// When both ``MaxEmptyLinesToKeep`` and ``OverEmptyLines`` are set to 2,
+ /// When both `MaxEmptyLinesToKeep` and `OverEmptyLines` are set to 2,
/// it formats like below.
/// \code
/// int a; // all these
@@ -600,7 +600,7 @@ struct FormatStyle {
/// int abcdef; // aligned
/// \endcode
///
- /// When ``MaxEmptyLinesToKeep`` is set to 2 and ``OverEmptyLines`` is set
+ /// When `MaxEmptyLinesToKeep` is set to 2 and `OverEmptyLines` is set
/// to 1, it formats like below.
/// \code
/// int a; // these are
@@ -633,7 +633,7 @@ struct FormatStyle {
/// Control of trailing comments.
///
/// The alignment stops at closing braces after a line break, and only
- /// followed by other closing braces, a (``do-``) ``while``, a lambda call, or
+ /// followed by other closing braces, a (`do-`) `while`, a lambda call, or
/// a semicolon.
///
/// \note
@@ -651,8 +651,8 @@ struct FormatStyle {
TrailingCommentsAlignmentStyle AlignTrailingComments;
/// If a function call or braced initializer list doesn't fit on a line, allow
- /// putting all arguments onto the next line, even if ``BinPackArguments`` is
- /// ``false``.
+ /// putting all arguments onto the next line, even if `BinPackArguments` is
+ /// `false`.
/// \code
/// true:
/// callFunction(
@@ -667,14 +667,14 @@ struct FormatStyle {
/// \version 9
bool AllowAllArgumentsOnNextLine;
- /// This option is **deprecated**. See ``NextLine`` of
- /// ``PackConstructorInitializers``.
+ /// This option is **deprecated**. See `NextLine` of
+ /// `PackConstructorInitializers`.
/// \version 9
// bool AllowAllConstructorInitializersOnNextLine;
/// If the function declaration doesn't fit on a line,
/// allow putting all parameters of a function declaration onto
- /// the next line even if ``BinPackParameters`` is ``OnePerLine``.
+ /// the next line even if `BinPackParameters` is `OnePerLine`.
/// \code
/// true:
/// void myFunction(
@@ -702,7 +702,7 @@ struct FormatStyle {
/// noexcept(baz(arg2)));
/// \endcode
BBNSS_Never,
- /// For a simple ``noexcept`` there is no line break allowed, but when we
+ /// For a simple `noexcept` there is no line break allowed, but when we
/// have a condition it is.
/// \code
/// void foo(int arg1,
@@ -714,8 +714,8 @@ struct FormatStyle {
/// \endcode
BBNSS_OnlyWithParen,
/// Line breaks are allowed. But note that because of the associated
- /// penalties ``clang-format`` often prefers not to break before the
- /// ``noexcept``.
+ /// penalties `clang-format` often prefers not to break before the
+ /// `noexcept`.
/// \code
/// void foo(int arg1,
/// double arg2) noexcept;
@@ -727,13 +727,13 @@ struct FormatStyle {
BBNSS_Always,
};
- /// Controls if there could be a line break before a ``noexcept`` specifier.
+ /// Controls if there could be a line break before a `noexcept` specifier.
/// \version 18
BreakBeforeNoexceptSpecifierStyle AllowBreakBeforeNoexceptSpecifier;
- /// Allow breaking before ``Q_Property`` keywords ``READ``, ``WRITE``, etc. as
- /// if they were preceded by a comma (``,``). This allows them to be formatted
- /// according to ``BinPackParameters``.
+ /// Allow breaking before `Q_Property` keywords `READ`, `WRITE`, etc. as
+ /// if they were preceded by a comma (`,`). This allows them to be formatted
+ /// according to `BinPackParameters`.
/// \version 22
bool AllowBreakBeforeQtProperty;
@@ -765,7 +765,7 @@ struct FormatStyle {
SBS_Always,
};
- /// Dependent on the value, ``while (true) { continue; }`` can be put on a
+ /// Dependent on the value, `while (true) { continue; }` can be put on a
/// single line.
/// \version 3.5
ShortBlockStyle AllowShortBlocksOnASingleLine;
@@ -783,7 +783,7 @@ struct FormatStyle {
/// \version 19
bool AllowShortCaseExpressionOnASingleLine;
- /// If ``true``, short case labels will be contracted to a single line.
+ /// If `true`, short case labels will be contracted to a single line.
/// \code
/// true: false:
/// switch (a) { vs. switch (a) {
@@ -835,13 +835,13 @@ struct FormatStyle {
///
/// They can be read as a whole for compatibility. The choices are:
///
- /// * ``None``
+ /// * `None`
/// Never merge functions into a single line.
///
- /// * ``InlineOnly``
- /// Only merge functions defined inside a class. Same as ``inline``,
- /// except it does not implies ``empty``: i.e. top level empty functions
- /// are not merged either. See ``Inline`` of ``ShortFunctionStyle``.
+ /// * `InlineOnly`
+ /// Only merge functions defined inside a class. Same as `inline`,
+ /// except it does not implies `empty`: i.e. top level empty functions
+ /// are not merged either. See `Inline` of `ShortFunctionStyle`.
/// \code
/// class Foo {
/// void f() { foo(); }
@@ -853,8 +853,8 @@ struct FormatStyle {
/// }
/// \endcode
///
- /// * ``Empty``
- /// Only merge empty functions. See ``Empty`` of ``ShortFunctionStyle``.
+ /// * `Empty`
+ /// Only merge empty functions. See `Empty` of `ShortFunctionStyle`.
/// \code
/// void f() {}
/// void f2() {
@@ -862,9 +862,9 @@ struct FormatStyle {
/// }
/// \endcode
///
- /// * ``Inline``
- /// Only merge functions defined inside a class. Implies ``empty``. See
- /// ``Inline`` and ``Empty`` of ``ShortFunctionStyle``.
+ /// * `Inline`
+ /// Only merge functions defined inside a class. Implies `empty`. See
+ /// `Inline` and `Empty` of `ShortFunctionStyle`.
/// \code
/// class Foo {
/// void f() { foo(); }
@@ -875,7 +875,7 @@ struct FormatStyle {
/// void f() {}
/// \endcode
///
- /// * ``All``
+ /// * `All`
/// Merge all functions fitting on a single line.
/// \code
/// class Foo {
@@ -885,7 +885,7 @@ struct FormatStyle {
/// \endcode
///
/// Also can be specified as a nested configuration flag:
- /// \code
+ /// \code{.yaml}
/// # Example of usage:
/// AllowShortFunctionsOnASingleLine: InlineOnly
///
@@ -950,7 +950,7 @@ struct FormatStyle {
}
};
- /// Dependent on the value, ``int f() { return 0; }`` can be put on a
+ /// Dependent on the value, `int f() { return 0; }` can be put on a
/// single line.
/// \version 3.5
ShortFunctionStyle AllowShortFunctionsOnASingleLine;
@@ -1022,7 +1022,7 @@ struct FormatStyle {
SIS_AllIfsAndElse,
};
- /// Dependent on the value, ``if (a) return;`` can be put on a single line.
+ /// Dependent on the value, `if (a) return;` can be put on a single line.
/// \version 3.3
ShortIfStyle AllowShortIfStatementsOnASingleLine;
@@ -1055,27 +1055,27 @@ struct FormatStyle {
SLS_All,
};
- /// Dependent on the value, ``auto lambda []() { return 0; }`` can be put on a
+ /// Dependent on the value, `auto lambda []() { return 0; }` can be put on a
/// single line.
/// \version 9
ShortLambdaStyle AllowShortLambdasOnASingleLine;
- /// If ``true``, ``while (true) continue;`` can be put on a single
+ /// If `true`, `while (true) continue;` can be put on a single
/// line.
/// \version 3.7
bool AllowShortLoopsOnASingleLine;
- /// If ``true``, ``namespace a { class b; }`` can be put on a single line.
+ /// If `true`, `namespace a { class b; }` can be put on a single line.
/// \version 20
bool AllowShortNamespacesOnASingleLine;
- /// Different styles for merging short records (``class``,``struct``, and
- /// ``union``).
+ /// Different styles for merging short records (`class`,`struct`, and
+ /// `union`).
enum ShortRecordStyle : int8_t {
/// Never merge records into a single line.
SRS_Never,
/// Only merge empty records if the opening brace was not wrapped,
- /// i.e. the corresponding ``BraceWrapping.After...`` option was not set.
+ /// i.e. the corresponding `BraceWrapping.After...` option was not set.
SRS_EmptyAndAttached,
/// Only merge empty records.
/// \code
@@ -1094,7 +1094,7 @@ struct FormatStyle {
SRS_Always
};
- /// Dependent on the value, ``struct bar { int i; };`` can be put on a single
+ /// Dependent on the value, `struct bar { int i; };` can be put on a single
/// line.
/// \version 23
ShortRecordStyle AllowShortRecordOnASingleLine;
@@ -1103,7 +1103,7 @@ struct FormatStyle {
/// This option is **deprecated** and is retained for backwards compatibility.
enum DefinitionReturnTypeBreakingStyle : int8_t {
/// Break after return type automatically.
- /// ``PenaltyReturnTypeOnItsOwnLine`` is taken into account.
+ /// `PenaltyReturnTypeOnItsOwnLine` is taken into account.
DRTBS_None,
/// Always break after the return type.
DRTBS_All,
@@ -1114,9 +1114,9 @@ struct FormatStyle {
/// Different ways to break after the function definition or
/// declaration return type.
enum ReturnTypeBreakingStyle : int8_t {
- /// This is **deprecated**. See ``Automatic`` below.
+ /// This is **deprecated**. See `Automatic` below.
RTBS_None,
- /// Break after return type based on ``PenaltyReturnTypeOnItsOwnLine``.
+ /// Break after return type based on `PenaltyReturnTypeOnItsOwnLine`.
/// \code
/// class A {
/// int f() { return 0; };
@@ -1127,7 +1127,7 @@ struct FormatStyle {
/// LongName::AnotherLongName();
/// \endcode
RTBS_Automatic,
- /// Same as ``Automatic`` above, except that there is no break after short
+ /// Same as `Automatic` above, except that there is no break after short
/// return types.
/// \code
/// class A {
@@ -1210,17 +1210,17 @@ struct FormatStyle {
/// \version 3.7
DefinitionReturnTypeBreakingStyle AlwaysBreakAfterDefinitionReturnType;
- /// This option is renamed to ``BreakAfterReturnType``.
+ /// This option is renamed to `BreakAfterReturnType`.
/// \version 3.8
/// @deprecated
// ReturnTypeBreakingStyle AlwaysBreakAfterReturnType;
- /// If ``true``, always break before multiline string literals.
+ /// If `true`, always break before multiline string literals.
///
/// This flag is mean to make cases where there are multiple multiline strings
/// in a file look more consistent. Thus, it will only take effect if wrapping
/// the string at that point leads to it being indented
- /// ``ContinuationIndentWidth`` spaces from the start of the line.
+ /// `ContinuationIndentWidth` spaces from the start of the line.
/// \code
/// true: false:
/// aaaa = vs. aaaa = "bbbb"
@@ -1243,7 +1243,7 @@ struct FormatStyle {
/// \endcode
BTDS_Leave,
/// Do not force break before declaration.
- /// ``PenaltyBreakTemplateDeclaration`` is taken into account.
+ /// `PenaltyBreakTemplateDeclaration` is taken into account.
/// \code
/// template <typename T> T foo() {
/// }
@@ -1276,7 +1276,7 @@ struct FormatStyle {
BTDS_Yes
};
- /// This option is renamed to ``BreakTemplateDeclarations``.
+ /// This option is renamed to `BreakTemplateDeclarations`.
/// \version 3.4
/// @deprecated
// BreakTemplateDeclarationsStyle AlwaysBreakTemplateDeclarations;
@@ -1300,12 +1300,12 @@ struct FormatStyle {
/// \version 12
std::vector<std::string> AttributeMacros;
- /// This option is **deprecated**. See ``BinPack`` of ``PackArguments``.
+ /// This option is **deprecated**. See `BinPack` of `PackArguments`.
/// \version 3.7
// bool BinPackArguments;
- /// If ``BinPackLongBracedList`` is ``true`` it overrides
- /// ``BinPackArguments`` if there are 20 or more items in a braced
+ /// If `BinPackLongBracedList` is `true` it overrides
+ /// `BinPackArguments` if there are 20 or more items in a braced
/// initializer list.
/// \code
/// BinPackLongBracedList: false vs. BinPackLongBracedList: true
@@ -1320,30 +1320,30 @@ struct FormatStyle {
/// \version 21
bool BinPackLongBracedList;
- /// This option is **deprecated**. See ``BinPack`` of ``PackParameters``.
+ /// This option is **deprecated**. See `BinPack` of `PackParameters`.
/// \version 3.7
// BinPackParametersStyle BinPackParameters;
- /// Styles for adding spacing around ``:`` in bitfield definitions.
+ /// Styles for adding spacing around `:` in bitfield definitions.
enum BitFieldColonSpacingStyle : int8_t {
- /// Add one space on each side of the ``:``
+ /// Add one space on each side of the `:`
/// \code
/// unsigned bf : 2;
/// \endcode
BFCS_Both,
- /// Add no space around the ``:`` (except when needed for
- /// ``AlignConsecutiveBitFields``).
+ /// Add no space around the `:` (except when needed for
+ /// `AlignConsecutiveBitFields`).
/// \code
/// unsigned bf:2;
/// \endcode
BFCS_None,
- /// Add space before the ``:`` only
+ /// Add space before the `:` only
/// \code
/// unsigned bf :2;
/// \endcode
BFCS_Before,
- /// Add space after the ``:`` only (space may be added before if
- /// needed for ``AlignConsecutiveBitFields``).
+ /// Add space after the `:` only (space may be added before if
+ /// needed for `AlignConsecutiveBitFields`).
/// \code
/// unsigned bf: 2;
/// \endcode
@@ -1354,7 +1354,7 @@ struct FormatStyle {
BitFieldColonSpacingStyle BitFieldColonSpacing;
/// The number of columns to use to indent the contents of braced init lists.
- /// If unset or negative, ``ContinuationIndentWidth`` is used.
+ /// If unset or negative, `ContinuationIndentWidth` is used.
/// \code
/// AlignAfterOpenBracket: AlwaysBreak
/// BracedInitializerIndentWidth: 2
@@ -1421,7 +1421,7 @@ struct FormatStyle {
};
/// Precise control over the wrapping of braces.
- /// \code
+ /// \code{.yaml}
/// # Should be declared this way:
/// BreakBeforeBraces: Custom
/// BraceWrapping:
@@ -1455,7 +1455,7 @@ struct FormatStyle {
/// \endcode
bool AfterClass;
- /// Wrap control statements (``if``/``for``/``while``/``switch``/..).
+ /// Wrap control statements (`if`/`for`/`while`/`switch`/..).
BraceWrappingAfterControlStatementStyle AfterControlStatement;
/// Wrap enum definitions.
/// \code
@@ -1504,7 +1504,7 @@ struct FormatStyle {
/// Wrap ObjC definitions (interfaces, implementations...).
/// \note
/// @autoreleasepool and @synchronized blocks are wrapped
- /// according to ``AfterControlStatement`` flag.
+ /// according to `AfterControlStatement` flag.
/// \endnote
bool AfterObjCDeclaration;
/// Wrap struct definitions.
@@ -1549,7 +1549,7 @@ struct FormatStyle {
/// }
/// \endcode
bool AfterExternBlock; // Partially superseded by IndentExternBlock
- /// Wrap before ``catch``.
+ /// Wrap before `catch`.
/// \code
/// true:
/// try {
@@ -1565,7 +1565,7 @@ struct FormatStyle {
/// }
/// \endcode
bool BeforeCatch;
- /// Wrap before ``else``.
+ /// Wrap before `else`.
/// \code
/// true:
/// if (foo()) {
@@ -1596,7 +1596,7 @@ struct FormatStyle {
/// });
/// \endcode
bool BeforeLambdaBody;
- /// Wrap before ``while``.
+ /// Wrap before `while`.
/// \code
/// true:
/// do {
@@ -1612,11 +1612,11 @@ struct FormatStyle {
bool BeforeWhile;
/// Indent the wrapped braces themselves.
bool IndentBraces;
- /// If ``false``, empty function body can be put on a single line.
+ /// If `false`, empty function body can be put on a single line.
/// This option is used only if the opening brace of the function has
- /// already been wrapped, i.e. the ``AfterFunction`` brace wrapping mode is
+ /// already been wrapped, i.e. the `AfterFunction` brace wrapping mode is
/// set, and the function could/should not be put on a single line (as per
- /// ``AllowShortFunctionsOnASingleLine`` and constructor formatting
+ /// `AllowShortFunctionsOnASingleLine` and constructor formatting
/// options).
/// \code
/// false: true:
@@ -1626,9 +1626,9 @@ struct FormatStyle {
/// \endcode
///
bool SplitEmptyFunction;
- /// If ``false``, empty record (e.g. class, struct or union) body
+ /// If `false`, empty record (e.g. class, struct or union) body
/// can be put on a single line. This option is used only if the opening
- /// brace of the record has already been wrapped, i.e. the ``AfterClass``
+ /// brace of the record has already been wrapped, i.e. the `AfterClass`
/// (for classes) brace wrapping mode is set.
/// \code
/// false: true:
@@ -1638,9 +1638,9 @@ struct FormatStyle {
/// \endcode
///
bool SplitEmptyRecord;
- /// If ``false``, empty namespace body can be put on a single line.
+ /// If `false`, empty namespace body can be put on a single line.
/// This option is used only if the opening brace of the namespace has
- /// already been wrapped, i.e. the ``AfterNamespace`` brace wrapping mode is
+ /// already been wrapped, i.e. the `AfterNamespace` brace wrapping mode is
/// set.
/// \code
/// false: true:
@@ -1654,7 +1654,7 @@ struct FormatStyle {
/// Control of individual brace wrapping cases.
///
- /// If ``BreakBeforeBraces`` is set to ``Custom``, use this to specify how
+ /// If `BreakBeforeBraces` is set to `Custom`, use this to specify how
/// each individual brace case should be handled. Otherwise, this is ignored.
/// \code{.yaml}
/// # Example of usage:
@@ -1737,7 +1737,7 @@ struct FormatStyle {
/// }
/// \endcode
ABS_Leave,
- /// Same as ``Leave`` except that it applies to all attributes of the group.
+ /// Same as `Leave` except that it applies to all attributes of the group.
/// \code
/// [[deprecated("Don't use this version")]]
/// [[nodiscard]]
@@ -1777,13 +1777,13 @@ struct FormatStyle {
/// Break after a group of C++11 attributes before variable or function
/// (including constructor/destructor) declaration/definition names or before
- /// control statements, i.e. ``if``, ``switch`` (including ``case`` and
- /// ``default`` labels), ``for``, and ``while`` statements.
+ /// control statements, i.e. `if`, `switch` (including `case` and
+ /// `default` labels), `for`, and `while` statements.
/// \version 16
AttributeBreakingStyle BreakAfterAttributes;
/// Force break after the left bracket of a braced initializer list (when
- /// ``Cpp11BracedListStyle`` is ``true``) when the list exceeds the column
+ /// `Cpp11BracedListStyle` is `true`) when the list exceeds the column
/// limit.
/// \code
/// true: false:
@@ -1837,8 +1837,8 @@ struct FormatStyle {
/// \version 19
ReturnTypeBreakingStyle BreakAfterReturnType;
- /// If ``true``, clang-format will always break after a Json array ``[``
- /// otherwise it will scan until the closing ``]`` to determine if it should
+ /// If `true`, clang-format will always break after a Json array `[`
+ /// otherwise it will scan until the closing `]` to determine if it should
/// add newlines between elements (prettier compatible).
///
/// \note
@@ -1958,7 +1958,7 @@ struct FormatStyle {
/// } // namespace N
/// \endcode
BS_Attach,
- /// Like ``Attach``, but break before braces on function, namespace and
+ /// Like `Attach`, but break before braces on function, namespace and
/// class definitions.
/// \code
/// namespace N
@@ -2008,7 +2008,7 @@ struct FormatStyle {
/// } // namespace N
/// \endcode
BS_Linux,
- /// Like ``Attach``, but break before braces on enum, function, and record
+ /// Like `Attach`, but break before braces on enum, function, and record
/// definitions.
/// \code
/// namespace N {
@@ -2058,8 +2058,8 @@ struct FormatStyle {
/// } // namespace N
/// \endcode
BS_Mozilla,
- /// Like ``Attach``, but break before function definitions, ``catch``, and
- /// ``else``.
+ /// Like `Attach`, but break before function definitions, `catch`, and
+ /// `else`.
/// \code
/// namespace N {
/// enum E {
@@ -2168,7 +2168,7 @@ struct FormatStyle {
/// } // namespace N
/// \endcode
BS_Allman,
- /// Like ``Allman`` but always indent braces and line up code with braces.
+ /// Like `Allman` but always indent braces and line up code with braces.
/// \code
/// namespace N
/// {
@@ -2291,7 +2291,7 @@ struct FormatStyle {
/// } // namespace N
/// \endcode
BS_GNU,
- /// Like ``Attach``, but break before functions.
+ /// Like `Attach`, but break before functions.
/// \code
/// namespace N {
/// enum E {
@@ -2338,7 +2338,7 @@ struct FormatStyle {
/// } // namespace N
/// \endcode
BS_WebKit,
- /// Configure each individual brace in ``BraceWrapping``.
+ /// Configure each individual brace in `BraceWrapping`.
BS_Custom
};
@@ -2347,7 +2347,7 @@ struct FormatStyle {
BraceBreakingStyle BreakBeforeBraces;
/// Force break before the right bracket of a braced initializer list (when
- /// ``Cpp11BracedListStyle`` is ``true``) when the list exceeds the column
+ /// `Cpp11BracedListStyle` is `true`) when the list exceeds the column
/// limit. The break before the right bracket is only made if there is a
/// break after the opening bracket.
/// \code
@@ -2411,16 +2411,16 @@ struct FormatStyle {
/// Different ways to break before concept declarations.
enum BreakBeforeConceptDeclarationsStyle : int8_t {
- /// Keep the template declaration line together with ``concept``.
+ /// Keep the template declaration line together with `concept`.
/// \code
/// template <typename T> concept C = ...;
/// \endcode
BBCDS_Never,
- /// Breaking between template declaration and ``concept`` is allowed. The
+ /// Breaking between template declaration and `concept` is allowed. The
/// actual behavior depends on the content and line breaking rules and
/// penalties.
BBCDS_Allowed,
- /// Always break before ``concept``, putting it in the line after the
+ /// Always break before `concept`, putting it in the line after the
/// template declaration.
/// \code
/// template <typename T>
@@ -2481,14 +2481,14 @@ struct FormatStyle {
};
/// The function declaration/definition return type breaking style to use.
- /// Trailing return types (``auto f() -> T``) are not affected. To have
- /// identifier macros (e.g. ``__always_inline``) treated as specifiers,
- /// add them to ``AttributeMacros``.
+ /// Trailing return types (`auto f() -> T`) are not affected. To have
+ /// identifier macros (e.g. `__always_inline`) treated as specifiers,
+ /// add them to `AttributeMacros`.
/// \version 23
BreakBeforeReturnTypeStyle BreakBeforeReturnType;
- /// If ``true``, break before a template closing bracket (``>``) when there is
- /// a line break after the matching opening bracket (``<``).
+ /// If `true`, break before a template closing bracket (`>`) when there is
+ /// a line break after the matching opening bracket (`<`).
/// \code
/// true:
/// template <typename Foo, typename Bar>
@@ -2514,7 +2514,7 @@ struct FormatStyle {
/// \version 21
bool BreakBeforeTemplateCloser;
- /// If ``true``, ternary operators will be placed after line breaks.
+ /// If `true`, ternary operators will be placed after line breaks.
/// \code
/// true:
/// veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription
@@ -2563,14 +2563,14 @@ struct FormatStyle {
/// A rule that specifies how to break a specific set of binary operators.
/// \version 23
struct BinaryOperationBreakRule {
- /// The list of operators this rule applies to, e.g. ``&&``, ``||``, ``|``.
- /// Alternative spellings (e.g. ``and`` for ``&&``) are accepted.
+ /// The list of operators this rule applies to, e.g. `&&`, `||`, `|`.
+ /// Alternative spellings (e.g. `and` for `&&`) are accepted.
std::vector<tok::TokenKind> Operators;
- /// The break style for these operators (defaults to ``OnePerLine``).
+ /// The break style for these operators (defaults to `OnePerLine`).
BreakBinaryOperationsStyle Style;
/// Minimum number of operands in a chain before the rule triggers.
- /// For example, ``a && b && c`` is a chain of length 3.
- /// ``0`` means always break (when the line is too long).
+ /// For example, `a && b && c` is a chain of length 3.
+ /// `0` means always break (when the line is too long).
unsigned MinChainLength;
bool operator==(const BinaryOperationBreakRule &R) const {
return Operators == R.Operators && Style == R.Style &&
@@ -2581,9 +2581,9 @@ struct FormatStyle {
}
};
- /// Options for ``BreakBinaryOperations``.
+ /// Options for `BreakBinaryOperations`.
///
- /// If specified as a simple string (e.g. ``OnePerLine``), it behaves like
+ /// If specified as a simple string (e.g. `OnePerLine`), it behaves like
/// the original enum and applies to all binary operators.
///
/// If specified as a struct, allows per-operator configuration:
@@ -2597,7 +2597,7 @@ struct FormatStyle {
/// \endcode
/// \version 23
struct BreakBinaryOperationsOptions {
- /// The default break style for operators not covered by ``PerOperator``.
+ /// The default break style for operators not covered by `PerOperator`.
BreakBinaryOperationsStyle Default;
/// Per-operator override rules.
std::vector<BinaryOperationBreakRule> PerOperator;
@@ -2675,7 +2675,7 @@ struct FormatStyle {
/// \version 5
BreakConstructorInitializersStyle BreakConstructorInitializers;
- /// If ``true``, clang-format will always break before function declaration
+ /// If `true`, clang-format will always break before function declaration
/// parameters.
/// \code
/// true:
@@ -2689,7 +2689,7 @@ struct FormatStyle {
/// \version 23
bool BreakFunctionDeclarationParameters;
- /// If ``true``, clang-format will always break before function definition
+ /// If `true`, clang-format will always break before function definition
/// parameters.
/// \code
/// true:
@@ -2758,7 +2758,7 @@ struct FormatStyle {
/// The column limit.
///
- /// A column limit of ``0`` means that there is no column limit. In this case,
+ /// 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 unless they contradict other rules.
/// \version 3.7
@@ -2818,8 +2818,8 @@ struct FormatStyle {
/// \version 19
BreakTemplateDeclarationsStyle BreakTemplateDeclarations;
- /// If ``true``, consecutive namespace declarations will be on the same
- /// line. If ``false``, each namespace is declared on a new line.
+ /// If `true`, consecutive namespace declarations will be on the same
+ /// line. If `false`, each namespace is declared on a new line.
/// \code
/// true:
/// namespace Foo { namespace Bar {
@@ -2842,8 +2842,8 @@ struct FormatStyle {
/// \version 5
bool CompactNamespaces;
- /// This option is **deprecated**. See ``CurrentLine`` of
- /// ``PackConstructorInitializers``.
+ /// This option is **deprecated**. See `CurrentLine` of
+ /// `PackConstructorInitializers`.
/// \version 3.7
// bool ConstructorInitializerAllOnOneLineOrOnePerLine;
@@ -2890,7 +2890,7 @@ struct FormatStyle {
/// 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
+ /// `{}` were the parentheses of a function call with that name. If there
/// is no name, a zero-length name is assumed.
/// \code
/// vector<int> x{1, 2, 3, 4};
@@ -2901,7 +2901,7 @@ struct FormatStyle {
/// value};
/// \endcode
BLS_FunctionCall,
- /// Same as ``FunctionCall``, except for the handling of a comment at the
+ /// Same as `FunctionCall`, except for the handling of a comment at the
/// begin, it then aligns everything following with the comment.
///
/// * No spaces inside the braced list. (Even for a comment at the first
@@ -2925,16 +2925,16 @@ struct FormatStyle {
/// \version 3.4
BracedListStyle Cpp11BracedListStyle;
- /// This option is **deprecated**. See ``DeriveLF`` and ``DeriveCRLF`` of
- /// ``LineEnding``.
+ /// This option is **deprecated**. See `DeriveLF` and `DeriveCRLF` of
+ /// `LineEnding`.
/// \version 10
// bool DeriveLineEnding;
- /// If ``true``, analyze the formatted file for the most common
- /// alignment of ``&`` and ``*``.
+ /// If `true`, analyze the formatted file for the most common
+ /// alignment of `&` and `*`.
/// Pointer and reference alignment styles are going to be updated according
/// to the preferences found in the file.
- /// ``PointerAlignment`` is then used only as fallback.
+ /// `PointerAlignment` is then used only as fallback.
/// \version 3.7
bool DerivePointerAlignment;
@@ -2943,7 +2943,7 @@ struct FormatStyle {
bool DisableFormat;
/// Different styles for empty line after access modifiers.
- /// ``EmptyLineBeforeAccessModifier`` configuration handles the number of
+ /// `EmptyLineBeforeAccessModifier` configuration handles the number of
/// empty lines between two access modifiers.
enum EmptyLineAfterAccessModifierStyle : int8_t {
/// Remove all empty lines after access modifiers.
@@ -2988,7 +2988,7 @@ struct FormatStyle {
};
/// Defines when to put an empty line after access modifiers.
- /// ``EmptyLineBeforeAccessModifier`` configuration handles the number of
+ /// `EmptyLineBeforeAccessModifier` configuration handles the number of
/// empty lines between two access modifiers.
/// \version 13
EmptyLineAfterAccessModifierStyle EmptyLineAfterAccessModifier;
@@ -3056,7 +3056,7 @@ struct FormatStyle {
/// \version 12
EmptyLineBeforeAccessModifierStyle EmptyLineBeforeAccessModifier;
- /// Styles for ``enum`` trailing commas.
+ /// Styles for `enum` trailing commas.
enum EnumTrailingCommaStyle : int8_t {
/// Don't insert or remove trailing commas.
/// \code
@@ -3078,10 +3078,10 @@ struct FormatStyle {
ETC_Remove,
};
- /// Insert a comma (if missing) or remove the comma at the end of an ``enum``
+ /// Insert a comma (if missing) or remove the comma at the end of an `enum`
/// enumerator list.
/// \warning
- /// Setting this option to any value other than ``Leave`` could lead to
+ /// Setting this option to any value other than `Leave` could lead to
/// incorrect code formatting due to clang-format's lack of complete semantic
/// information. As such, extra care should be taken to review code changes
/// made by this option.
@@ -3089,7 +3089,7 @@ struct FormatStyle {
/// \version 21
EnumTrailingCommaStyle EnumTrailingComma;
- /// If ``true``, clang-format detects whether function calls and
+ /// 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
@@ -3104,9 +3104,9 @@ struct FormatStyle {
/// \version 3.7
bool ExperimentalAutoDetectBinPacking;
- /// If ``true``, clang-format adds missing namespace end comments for
+ /// If `true`, clang-format adds missing namespace end comments for
/// namespaces and fixes invalid existing ones. This doesn't affect short
- /// namespaces, which are controlled by ``ShortNamespaceLines``.
+ /// namespaces, which are controlled by `ShortNamespaceLines`.
/// \code
/// true: false:
/// namespace longNamespace { vs. namespace longNamespace {
@@ -3156,20 +3156,20 @@ struct FormatStyle {
/// IfMacros: [IF]
/// \endcode
///
- /// For example: `KJ_IF_MAYBE
- /// <https://github.com/capnproto/capnproto/blob/master/kjdoc/tour.md#maybes>`_
+ /// For example:
+ /// [KJ_IF_MAYBE](https://github.com/capnproto/capnproto/blob/master/kjdoc/tour.md#maybes)
/// \version 13
std::vector<std::string> IfMacros;
/// Specify whether access modifiers should have their own indentation level.
///
- /// When ``false``, access modifiers are indented (or outdented) relative to
- /// the record members, respecting the ``AccessModifierOffset``. Record
+ /// When `false`, access modifiers are indented (or outdented) relative to
+ /// the record members, respecting the `AccessModifierOffset`. Record
/// members are indented one level below the record.
- /// When ``true``, access modifiers get their own indentation level. As a
+ /// When `true`, access modifiers get their own indentation level. As a
/// consequence, record members are always indented 2 levels below the record,
/// regardless of the access modifier presence. Value of the
- /// ``AccessModifierOffset`` is ignored.
+ /// `AccessModifierOffset` is ignored.
/// \code
/// false: true:
/// class C { vs. class C {
@@ -3190,10 +3190,10 @@ struct FormatStyle {
/// Indent case label blocks one level from the case label.
///
- /// When ``false``, the block following the case label uses the same
+ /// When `false`, the block following the case label uses the same
/// indentation level as for the case label, treating the case label the same
/// as an if-statement.
- /// When ``true``, the block gets indented as a scope block.
+ /// When `true`, the block gets indented as a scope block.
/// \code
/// false: true:
/// switch (fool) { vs. switch (fool) {
@@ -3213,7 +3213,7 @@ struct FormatStyle {
/// Indent case labels one level from the switch statement.
///
- /// When ``false``, use the same indentation level as for the switch
+ /// When `false`, use the same indentation level as for the switch
/// statement. Switch statement body is always indented one level more than
/// case labels (except the first block following the case label, which
/// itself indents the code - unless IndentCaseBlocks is enabled).
@@ -3230,7 +3230,7 @@ struct FormatStyle {
/// \version 3.3
bool IndentCaseLabels;
- /// If ``true``, clang-format will indent the body of an ``export { ... }``
+ /// If `true`, clang-format will indent the body of an `export { ... }`
/// block. This doesn't affect the formatting of anything else related to
/// exported declarations.
/// \code
@@ -3372,7 +3372,7 @@ struct FormatStyle {
PPDIS_BeforeHash,
/// Leaves indentation of directives as-is.
/// \note
- /// Ignores ``PPIndentWidth``.
+ /// Ignores `PPIndentWidth`.
/// \endnote
/// \code
/// #if FOO
@@ -3389,10 +3389,10 @@ struct FormatStyle {
PPDirectiveIndentStyle IndentPPDirectives;
/// Indent the requires clause in a template. This only applies when
- /// ``RequiresClausePosition`` is ``OwnLine``, ``OwnLineWithBrace``,
- /// or ``WithFollowing``.
+ /// `RequiresClausePosition` is `OwnLine`, `OwnLineWithBrace`,
+ /// or `WithFollowing`.
///
- /// In clang-format 12, 13 and 14 it was named ``IndentRequires``.
+ /// In clang-format 12, 13 and 14 it was named `IndentRequires`.
/// \code
/// true:
/// template <typename It>
@@ -3439,11 +3439,11 @@ struct FormatStyle {
/// \version 3.7
bool IndentWrappedFunctionNames;
- /// Insert braces after control statements (``if``, ``else``, ``for``, ``do``,
- /// and ``while``) in C++ unless the control statements are inside macro
+ /// Insert braces after control statements (`if`, `else`, `for`, `do`,
+ /// and `while`) in C++ unless the control statements are inside macro
/// definitions or the braces would enclose preprocessor directives.
/// \warning
- /// Setting this option to ``true`` could lead to incorrect code formatting
+ /// Setting this option to `true` could lead to incorrect code formatting
/// due to clang-format's lack of complete semantic information. As such,
/// extra care should be taken to review code changes made by this option.
/// \endwarning
@@ -3487,11 +3487,11 @@ struct FormatStyle {
TCS_Wrapped,
};
- /// If set to ``TCS_Wrapped`` will insert trailing commas in container
+ /// If set to `TCS_Wrapped` will insert trailing commas in container
/// literals (arrays and objects) that wrap across multiple lines.
/// It is currently only available for JavaScript
- /// and disabled by default ``TCS_None``.
- /// ``InsertTrailingCommas`` cannot be used together with ``BinPackArguments``
+ /// and disabled by default `TCS_None`.
+ /// `InsertTrailingCommas` cannot be used together with `BinPackArguments`
/// as inserting the comma disables bin-packing.
/// \code
/// TSC_Wrapped:
@@ -3507,7 +3507,7 @@ struct FormatStyle {
/// Separator format of integer literals of
diff erent bases.
///
- /// If negative, remove separators. If ``0``, leave the literal as is. If
+ /// If negative, remove separators. If `0`, leave the literal as is. If
/// positive, insert separators between digits starting from the rightmost
/// digit.
///
@@ -3522,18 +3522,18 @@ struct FormatStyle {
/// \endcode
///
/// You can also specify a minimum number of digits
- /// (``BinaryMinDigitsInsert``, ``DecimalMinDigitsInsert``, and
- /// ``HexMinDigitsInsert``) the integer literal must have in order for the
+ /// (`BinaryMinDigitsInsert`, `DecimalMinDigitsInsert`, and
+ /// `HexMinDigitsInsert`) the integer literal must have in order for the
/// separators to be inserted, and a maximum number of digits
- /// (``BinaryMaxDigitsRemove``, ``DecimalMaxDigitsRemove``, and
- /// ``HexMaxDigitsRemove``) until the separators are removed. This divides the
+ /// (`BinaryMaxDigitsRemove`, `DecimalMaxDigitsRemove`, and
+ /// `HexMaxDigitsRemove`) until the separators are removed. This divides the
/// literals in 3 regions, always without separator (up until including
- /// ``xxxMaxDigitsRemove``), maybe with, or without separators (up until
- /// excluding ``xxxMinDigitsInsert``), and finally always with separators.
+ /// `xxxMaxDigitsRemove`), maybe with, or without separators (up until
+ /// excluding `xxxMinDigitsInsert`), and finally always with separators.
/// \note
- /// ``BinaryMinDigits``, ``DecimalMinDigits``, and ``HexMinDigits`` are
- /// deprecated and renamed to ``BinaryMinDigitsInsert``,
- /// ``DecimalMinDigitsInsert``, and ``HexMinDigitsInsert``, respectively.
+ /// `BinaryMinDigits`, `DecimalMinDigits`, and `HexMinDigits` are
+ /// deprecated and renamed to `BinaryMinDigitsInsert`,
+ /// `DecimalMinDigitsInsert`, and `HexMinDigitsInsert`, respectively.
/// \endnote
struct IntegerLiteralSeparatorStyle {
/// Format separators in binary literals.
@@ -3635,7 +3635,7 @@ struct FormatStyle {
}
};
- /// Format integer literal separators (``'`` for C/C++ and ``_`` for C#, Java,
+ /// Format integer literal separators (`'` for C/C++ and `_` for C#, Java,
/// and JavaScript).
/// \version 16
IntegerLiteralSeparatorStyle IntegerLiteralSeparator;
@@ -3647,7 +3647,7 @@ struct FormatStyle {
/// Static imports are grouped separately and follow the same group rules.
/// By default, static imports are placed before non-static imports,
/// but this behavior is changed by another option,
- /// ``SortJavaStaticImport``.
+ /// `SortJavaStaticImport`.
///
/// In the .clang-format configuration file, this can be configured like
/// in the following yaml example. This will result in imports being
@@ -3749,17 +3749,17 @@ struct FormatStyle {
AtStartOfFile == R.AtStartOfFile;
}
};
- /// Which empty lines are kept. See ``MaxEmptyLinesToKeep`` for how many
+ /// Which empty lines are kept. See `MaxEmptyLinesToKeep` for how many
/// consecutive empty lines are kept.
/// \version 19
KeepEmptyLinesStyle KeepEmptyLines;
- /// This option is **deprecated**. See ``AtEndOfFile`` of ``KeepEmptyLines``.
+ /// This option is **deprecated**. See `AtEndOfFile` of `KeepEmptyLines`.
/// \version 17
// bool KeepEmptyLinesAtEOF;
- /// This option is **deprecated**. See ``AtStartOfBlock`` of
- /// ``KeepEmptyLines``.
+ /// This option is **deprecated**. See `AtStartOfBlock` of
+ /// `KeepEmptyLines`.
/// \version 3.7
// bool KeepEmptyLinesAtTheStartOfBlocks;
@@ -3797,9 +3797,9 @@ struct FormatStyle {
LBI_OuterScope,
};
- /// The indentation style of lambda bodies. ``Signature`` (the default)
+ /// The indentation style of lambda bodies. `Signature` (the default)
/// causes the lambda body to be indented one additional level relative to
- /// the indentation level of the signature. ``OuterScope`` forces the lambda
+ /// the indentation level of the signature. `OuterScope` forces the lambda
/// body to be indented one additional level relative to the parent scope
/// containing the lambda signature.
/// \version 13
@@ -3808,7 +3808,7 @@ struct FormatStyle {
/// Supported languages.
///
/// When stored in a configuration file, specifies the language, that the
- /// configuration targets. When passed to the ``reformat()`` function, enables
+ /// configuration targets. When passed to the `reformat()` function, enables
/// syntax features specific to the language.
enum LanguageKind : int8_t {
/// Do not use.
@@ -3827,13 +3827,12 @@ struct FormatStyle {
LK_Json,
/// Should be used for Objective-C, Objective-C++.
LK_ObjC,
- /// Should be used for Protocol Buffers
- /// (https://developers.google.com/protocol-buffers/).
+ /// Should be used for [Protocol Buffers](https://protobuf.dev/)
LK_Proto,
/// Should be used for TableGen code.
LK_TableGen,
- /// Should be used for Protocol Buffer messages in text format
- /// (https://developers.google.com/protocol-buffers/).
+ /// Should be used for [Protocol Buffer](https://protobuf.dev/) messages in
+ /// text format
LK_TextProto,
/// Should be used for Verilog and SystemVerilog.
/// https://standards.ieee.org/ieee/1800/6700/
@@ -3854,26 +3853,26 @@ struct FormatStyle {
/// The language that this format style targets.
/// \note
- /// You can specify the language (``C``, ``Cpp``, or ``ObjC``) for ``.h``
- /// files by adding a ``// clang-format Language:`` line before the first
- /// non-comment (and non-empty) line, e.g. ``// clang-format Language: Cpp``.
+ /// You can specify the language (`C`, `Cpp`, or `ObjC`) for `.h`
+ /// files by adding a `// clang-format Language:` line before the first
+ /// non-comment (and non-empty) line, e.g. `// clang-format Language: Cpp`.
/// \endnote
/// \version 3.5
LanguageKind Language;
/// Line ending style.
enum LineEndingStyle : int8_t {
- /// Use ``\n``.
+ /// Use `\n`.
LE_LF,
- /// Use ``\r\n``.
+ /// Use `\r\n`.
LE_CRLF,
- /// Use ``\n`` unless the input has more lines ending in ``\r\n``.
+ /// Use `\n` unless the input has more lines ending in `\r\n`.
LE_DeriveLF,
- /// Use ``\r\n`` unless the input has more lines ending in ``\n``.
+ /// Use `\r\n` unless the input has more lines ending in `\n`.
LE_DeriveCRLF,
};
- /// Line ending style (``\n`` or ``\r\n``) to use.
+ /// Line ending style (`\n` or `\r\n`) to use.
/// \version 16
LineEndingStyle LineEnding;
@@ -3921,7 +3920,7 @@ struct FormatStyle {
/// \endcode
///
/// will usually be interpreted as a call to a function A, and the
- /// multiplication expression will be formatted as ``a * b``.
+ /// multiplication expression will be formatted as `a * b`.
///
/// If we specify the macro definition:
/// \code{.yaml}
@@ -3930,15 +3929,16 @@ struct FormatStyle {
/// \endcode
///
/// the code will now be parsed as a declaration of the variable b of type a*,
- /// and formatted as ``a* b`` (depending on pointer-binding rules).
+ /// and formatted as `a* b` (depending on pointer-binding rules).
///
/// Features and restrictions:
- /// * Both function-like macros and object-like macros are supported.
- /// * Macro arguments must be used exactly once in the expansion.
- /// * No recursive expansion; macros referencing other macros will be
- /// ignored.
- /// * Overloading by arity is supported: for example, given the macro
- /// definitions A=x, A()=y, A(a)=a
+ ///
+ /// - Both function-like macros and object-like macros are supported.
+ /// - Macro arguments must be used exactly once in the expansion.
+ /// - No recursive expansion; macros referencing other macros will be
+ /// ignored.
+ /// - Overloading by arity is supported: for example, given the macro
+ /// definitions A=x, A()=y, A(a)=a
///
/// \code
/// A; -> x;
@@ -3951,7 +3951,7 @@ struct FormatStyle {
std::vector<std::string> Macros;
/// A vector of function-like macros whose invocations should be skipped by
- /// ``RemoveParentheses``.
+ /// `RemoveParentheses`.
/// \version 21
std::vector<std::string> MacrosSkippedByRemoveParentheses;
@@ -4065,7 +4065,7 @@ struct FormatStyle {
/// \endcode
NumericLiteralComponentStyle Prefix;
/// Format suffix case. This option excludes case-sensitive reserved
- /// suffixes, such as ``min`` in C++.
+ /// suffixes, such as `min` in C++.
/// \code
/// a = 1uLL; // Leave
/// a = 1ULL; // Upper
@@ -4088,19 +4088,19 @@ struct FormatStyle {
NumericLiteralCaseStyle NumericLiteralCase;
/// Controls bin-packing Objective-C protocol conformance list
- /// items into as few lines as possible when they go over ``ColumnLimit``.
+ /// items into as few lines as possible when they go over `ColumnLimit`.
///
- /// If ``Auto`` (the default), delegates to the value in
- /// ``BinPackParameters``. If that is ``BinPack``, bin-packs Objective-C
+ /// If `Auto` (the default), delegates to the value in
+ /// `BinPackParameters`. If that is `BinPack`, bin-packs Objective-C
/// protocol conformance list items into as few lines as possible
- /// whenever they go over ``ColumnLimit``.
+ /// whenever they go over `ColumnLimit`.
///
- /// If ``Always``, always bin-packs Objective-C protocol conformance
+ /// If `Always`, always bin-packs Objective-C protocol conformance
/// list items into as few lines as possible whenever they go over
- /// ``ColumnLimit``.
+ /// `ColumnLimit`.
///
- /// If ``Never``, lays out Objective-C protocol conformance list items
- /// onto individual lines whenever they go over ``ColumnLimit``.
+ /// If `Never`, lays out Objective-C protocol conformance list items
+ /// onto individual lines whenever they go over `ColumnLimit`.
///
/// \code{.objc}
/// Always (or Auto, if BinPackParameters==BinPack):
@@ -4188,13 +4188,13 @@ struct FormatStyle {
/// \version 23
bool ObjCSpaceAfterMethodDeclarationPrefix;
- /// Add a space after ``@property`` in Objective-C, i.e. use
- /// ``@property (readonly)`` instead of ``@property(readonly)``.
+ /// Add a space after `@property` in Objective-C, i.e. use
+ /// `@property (readonly)` instead of `@property(readonly)`.
/// \version 3.7
bool ObjCSpaceAfterProperty;
/// Add a space in front of an Objective-C protocol list, i.e. use
- /// ``Foo <Protocol>`` instead of ``Foo<Protocol>``.
+ /// `Foo <Protocol>` instead of `Foo<Protocol>`.
/// \version 3.7
bool ObjCSpaceBeforeProtocolList;
@@ -4203,8 +4203,8 @@ struct FormatStyle {
/// clang-format skips the comment and the next line. Otherwise, clang-format
/// skips lines containing a matched token.
/// \note
- /// This option does not apply to ``IntegerLiteralSeparator`` and
- /// ``NumericLiteralCase``.
+ /// This option does not apply to `IntegerLiteralSeparator` and
+ /// `NumericLiteralCase`.
/// \endnote
/// \code
/// // OneLineFormatOffRegex: ^(// NOLINT|logger$)
@@ -4243,8 +4243,8 @@ struct FormatStyle {
/// }
/// \endcode
BPAS_OnePerLine,
- /// Use the ``BreakAfter`` option to handle argument packing instead.
- /// If the ``BreakAfter`` limit is not exceeded, behave like ``BinPack``.
+ /// Use the `BreakAfter` option to handle argument packing instead.
+ /// If the `BreakAfter` limit is not exceeded, behave like `BinPack`.
BPAS_UseBreakAfter
};
@@ -4257,7 +4257,7 @@ struct FormatStyle {
/// An argument list with more arguments than the specified number will be
/// formatted with one argument per line. This option must be used with
- /// ``BinPack: UseBreakAfter``.
+ /// `BinPack: UseBreakAfter`.
/// \code
/// PackArguments:
/// BinPack: UseBreakAfter
@@ -4316,7 +4316,7 @@ struct FormatStyle {
/// ddddddddddddd()
/// \endcode
PCIS_CurrentLine,
- /// Same as ``PCIS_CurrentLine`` except that if all constructor initializers
+ /// Same as `PCIS_CurrentLine` except that if all constructor initializers
/// do not fit on the current line, try to fit them on the next line.
/// \code
/// Constructor() : a(), b()
@@ -4376,8 +4376,8 @@ struct FormatStyle {
/// int c);
/// \endcode
BPPS_AlwaysOnePerLine,
- /// Use the ``BreakAfter`` option to handle parameter packing instead.
- /// If the ``BreakAfter`` limit is not exceeded, behave like ``BinPack``.
+ /// Use the `BreakAfter` option to handle parameter packing instead.
+ /// If the `BreakAfter` limit is not exceeded, behave like `BinPack`.
BPPS_UseBreakAfter
};
@@ -4391,7 +4391,7 @@ struct FormatStyle {
/// A parameter list with more parameters than the specified number will be
/// formatted with one parameter per line. This option must be used with
- /// ``BinPack: UseBreakAfter``.
+ /// `BinPack: UseBreakAfter`.
/// \code
/// PackParameters:
/// BinPack: UseBreakAfter
@@ -4426,11 +4426,11 @@ struct FormatStyle {
/// \version 5
unsigned PenaltyBreakAssignment;
- /// The penalty for breaking a function call after ``call(``.
+ /// The penalty for breaking a function call after `call(`.
/// \version 3.7
unsigned PenaltyBreakBeforeFirstCallParameter;
- /// The penalty for breaking before a member access operator (``.``, ``->``).
+ /// The penalty for breaking before a member access operator (`.`, `->`).
/// \version 20
unsigned PenaltyBreakBeforeMemberAccess;
@@ -4438,15 +4438,15 @@ struct FormatStyle {
/// \version 3.7
unsigned PenaltyBreakComment;
- /// The penalty for breaking before the first ``<<``.
+ /// The penalty for breaking before the first `<<`.
/// \version 3.7
unsigned PenaltyBreakFirstLessLess;
- /// The penalty for breaking after ``(``.
+ /// The penalty for breaking after `(`.
/// \version 14
unsigned PenaltyBreakOpenParenthesis;
- /// The penalty for breaking after ``::``.
+ /// The penalty for breaking after `::`.
/// \version 18
unsigned PenaltyBreakScopeResolution;
@@ -4471,7 +4471,7 @@ struct FormatStyle {
/// \version 3.7
unsigned PenaltyReturnTypeOnItsOwnLine;
- /// The ``&``, ``&&`` and ``*`` alignment style.
+ /// The `&`, `&&` and `*` alignment style.
enum PointerAlignmentStyle : int8_t {
/// Align pointer to the left.
/// \code
@@ -4495,7 +4495,7 @@ struct FormatStyle {
PointerAlignmentStyle PointerAlignment;
/// The number of columns to use for indentation of preprocessor statements.
- /// When set to -1 (default) ``IndentWidth`` is used also for preprocessor
+ /// When set to -1 (default) `IndentWidth` is used also for preprocessor
/// statements.
/// \code
/// PPIndentWidth: 1
@@ -4530,7 +4530,7 @@ struct FormatStyle {
/// int const *a;
/// \endcode
QAS_Right,
- /// Change specifiers/qualifiers to be aligned based on ``QualifierOrder``.
+ /// Change specifiers/qualifiers to be aligned based on `QualifierOrder`.
/// With:
/// \code{.yaml}
/// QualifierOrder: [inline, static, type, const]
@@ -4546,7 +4546,7 @@ struct FormatStyle {
/// Different ways to arrange specifiers and qualifiers (e.g. const/volatile).
/// \warning
- /// Setting ``QualifierAlignment`` to something other than ``Leave``, COULD
+ /// Setting `QualifierAlignment` to something other than `Leave`, COULD
/// lead to incorrect code formatting due to incorrect decisions made due to
/// clang-formats lack of complete semantic information.
/// As such extra care should be taken to review code changes made by the use
@@ -4558,21 +4558,21 @@ struct FormatStyle {
/// The order in which the qualifiers appear.
/// The order is an array that can contain any of the following:
///
- /// * ``const``
- /// * ``inline``
- /// * ``static``
- /// * ``friend``
- /// * ``constexpr``
- /// * ``volatile``
- /// * ``restrict``
- /// * ``type``
+ /// * `const`
+ /// * `inline`
+ /// * `static`
+ /// * `friend`
+ /// * `constexpr`
+ /// * `volatile`
+ /// * `restrict`
+ /// * `type`
///
/// \note
- /// It must contain ``type``.
+ /// It must contain `type`.
/// \endnote
///
- /// Items to the left of ``type`` will be placed to the left of the type and
- /// aligned in the order supplied. Items to the right of ``type`` will be
+ /// Items to the left of `type` will be placed to the left of the type and
+ /// aligned in the order supplied. Items to the right of `type` will be
/// placed to the right of the type and aligned in the order supplied.
///
/// \code{.yaml}
@@ -4581,7 +4581,7 @@ struct FormatStyle {
/// \version 14
std::vector<std::string> QualifierOrder;
- /// See documentation of ``RawStringFormats``.
+ /// See documentation of `RawStringFormats`.
struct RawStringFormat {
/// The language of this raw string.
LanguageKind Language;
@@ -4610,8 +4610,8 @@ struct FormatStyle {
/// name will be reformatted assuming the specified language based on the
/// style for that language defined in the .clang-format file. If no style has
/// been defined in the .clang-format file for the specific language, a
- /// predefined style given by ``BasedOnStyle`` is used. If ``BasedOnStyle`` is
- /// not found, the formatting is based on ``LLVM`` style. A matching delimiter
+ /// predefined style given by `BasedOnStyle` is used. If `BasedOnStyle` is
+ /// not found, the formatting is based on `LLVM` style. A matching delimiter
/// takes precedence over a matching enclosing function name for determining
/// the language of the raw string contents.
///
@@ -4641,9 +4641,9 @@ struct FormatStyle {
/// \version 6
std::vector<RawStringFormat> RawStringFormats;
- /// The ``&`` and ``&&`` alignment style.
+ /// The `&` and `&&` alignment style.
enum ReferenceAlignmentStyle : int8_t {
- /// Align reference like ``PointerAlignment``.
+ /// Align reference like `PointerAlignment`.
RAS_Pointer,
/// Align reference to the left.
/// \code
@@ -4662,7 +4662,7 @@ struct FormatStyle {
RAS_Middle
};
- /// Reference alignment style (overrides ``PointerAlignment`` for references).
+ /// Reference alignment style (overrides `PointerAlignment` for references).
/// \version 13
ReferenceAlignmentStyle ReferenceAlignment;
@@ -4687,7 +4687,7 @@ struct FormatStyle {
/// \endcode
RCS_IndentOnly,
/// Apply indentation rules and reflow long comments into new lines, trying
- /// to obey the ``ColumnLimit``.
+ /// to obey the `ColumnLimit`.
/// \code
/// // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
/// // information
@@ -4704,13 +4704,13 @@ struct FormatStyle {
/// \version 3.8
ReflowCommentsStyle ReflowComments;
- /// Remove optional braces of control statements (``if``, ``else``, ``for``,
- /// and ``while``) in C++ according to the LLVM coding style.
+ /// Remove optional braces of control statements (`if`, `else`, `for`,
+ /// and `while`) in C++ according to the LLVM coding style.
/// \warning
/// This option will be renamed and expanded to support other styles.
/// \endwarning
/// \warning
- /// Setting this option to ``true`` could lead to incorrect code formatting
+ /// Setting this option to `true` could lead to incorrect code formatting
/// due to clang-format's lack of complete semantic information. As such,
/// extra care should be taken to review code changes made by this option.
/// \endwarning
@@ -4798,7 +4798,7 @@ struct FormatStyle {
/// \endcode
RPS_MultipleParentheses,
/// Also remove parentheses enclosing the expression in a
- /// ``return``/``co_return`` statement.
+ /// `return`/`co_return` statement.
/// \code
/// class __declspec(dllimport) X {};
/// co_return 0;
@@ -4809,7 +4809,7 @@ struct FormatStyle {
/// Remove redundant parentheses.
/// \warning
- /// Setting this option to any value other than ``Leave`` could lead to
+ /// Setting this option to any value other than `Leave` could lead to
/// incorrect code formatting due to clang-format's lack of complete semantic
/// information. As such, extra care should be taken to review code changes
/// made by this option.
@@ -4820,7 +4820,7 @@ struct FormatStyle {
/// Remove semicolons after the closing braces of functions and
/// constructors/destructors.
/// \warning
- /// Setting this option to ``true`` could lead to incorrect code formatting
+ /// Setting this option to `true` could lead to incorrect code formatting
/// due to clang-format's lack of complete semantic information. As such,
/// extra care should be taken to review code changes made by this option.
/// \endwarning
@@ -4835,10 +4835,10 @@ struct FormatStyle {
/// \version 16
bool RemoveSemicolon;
- /// The possible positions for the requires clause. The ``IndentRequires``
- /// option is only used if the ``requires`` is put on the start of a line.
+ /// The possible positions for the requires clause. The `IndentRequires`
+ /// option is only used if the `requires` is put on the start of a line.
enum RequiresClausePositionStyle : int8_t {
- /// Always put the ``requires`` clause on its own line (possibly followed by
+ /// Always put the `requires` clause on its own line (possibly followed by
/// a semicolon).
/// \code
/// template <typename T>
@@ -4859,7 +4859,7 @@ struct FormatStyle {
/// {...
/// \endcode
RCPS_OwnLine,
- /// As with ``OwnLine``, except, unless otherwise prohibited, place a
+ /// As with `OwnLine`, except, unless otherwise prohibited, place a
/// following open brace (of a function definition) to follow on the same
/// line.
/// \code
@@ -4894,7 +4894,7 @@ struct FormatStyle {
/// {...
/// \endcode
RCPS_WithPreceding,
- /// Try to put the ``requires`` clause together with the class or function
+ /// Try to put the `requires` clause together with the class or function
/// declaration.
/// \code
/// template <typename T>
@@ -4934,7 +4934,7 @@ struct FormatStyle {
RCPS_SingleLine,
};
- /// The position of the ``requires`` clause.
+ /// The position of the `requires` clause.
/// \version 15
RequiresClausePositionStyle RequiresClausePosition;
@@ -4950,7 +4950,7 @@ struct FormatStyle {
/// }
/// \endcode
REI_OuterScope,
- /// Align requires expression body relative to the ``requires`` keyword.
+ /// Align requires expression body relative to the `requires` keyword.
/// \code
/// template <typename T>
/// concept C = requires(T t) {
@@ -5027,7 +5027,7 @@ struct FormatStyle {
///
/// This determines the maximum length of short namespaces by counting
/// unwrapped lines (i.e. containing neither opening nor closing
- /// namespace brace) and makes ``FixNamespaceComments`` omit adding
+ /// namespace brace) and makes `FixNamespaceComments` omit adding
/// end comments for those.
/// \code
/// ShortNamespaceLines: 1 vs. ShortNamespaceLines: 0
@@ -5050,12 +5050,12 @@ struct FormatStyle {
/// Includes sorting options.
struct SortIncludesOptions {
- /// If ``true``, includes are sorted based on the other suboptions below.
- /// (``Never`` is deprecated by ``Enabled: false``.)
+ /// If `true`, includes are sorted based on the other suboptions below.
+ /// (`Never` is deprecated by `Enabled: false`.)
bool Enabled;
/// Whether or not includes are sorted in a case-insensitive fashion.
- /// (``CaseSensitive`` and ``CaseInsensitive`` are deprecated by
- /// ``IgnoreCase: false`` and ``IgnoreCase: true``, respectively.)
+ /// (`CaseSensitive` and `CaseInsensitive` are deprecated by
+ /// `IgnoreCase: false` and `IgnoreCase: true`, respectively.)
/// \code
/// true: false:
/// #include "A/B.h" vs. #include "A/B.h"
@@ -5092,7 +5092,7 @@ struct FormatStyle {
}
};
- /// Controls if and how clang-format will sort ``#includes``.
+ /// Controls if and how clang-format will sort `#includes`.
/// \version 3.8
SortIncludesOptions SortIncludes;
@@ -5115,7 +5115,7 @@ struct FormatStyle {
};
/// When sorting Java imports, by default static imports are placed before
- /// non-static imports. If ``JavaStaticImportAfterImport`` is ``After``,
+ /// non-static imports. If `JavaStaticImportAfterImport` is `After`,
/// static imports are placed after non-static imports.
/// \version 12
SortJavaStaticImportOptions SortJavaStaticImport;
@@ -5132,7 +5132,7 @@ struct FormatStyle {
/// \endcode
SUD_Never,
/// Using declarations are sorted in the order defined as follows:
- /// Split the strings by ``::`` and discard any initial empty strings. Sort
+ /// Split the strings by `::` and discard any initial empty strings. Sort
/// the lists of names lexicographically, and within those groups, names are
/// in case-insensitive lexicographic order.
/// \code
@@ -5144,7 +5144,7 @@ struct FormatStyle {
/// \endcode
SUD_Lexicographic,
/// Using declarations are sorted in the order defined as follows:
- /// Split the strings by ``::`` and discard any initial empty strings. The
+ /// Split the strings by `::` and discard any initial empty strings. The
/// last element of each list is a non-namespace name; all others are
/// namespace names. Sort the lists of names lexicographically, where the
/// sort order of individual names is that all non-namespace names come
@@ -5164,7 +5164,7 @@ struct FormatStyle {
/// \version 5
SortUsingDeclarationsOptions SortUsingDeclarations;
- /// If ``true``, a space is inserted after C style casts.
+ /// If `true`, a space is inserted after C style casts.
/// \code
/// true: false:
/// (int) i; vs. (int)i;
@@ -5172,7 +5172,7 @@ struct FormatStyle {
/// \version 3.5
bool SpaceAfterCStyleCast;
- /// If ``true``, a space is inserted after the logical not operator (``!``).
+ /// If `true`, a space is inserted after the logical not operator (`!`).
/// \code
/// true: false:
/// ! someExpression(); vs. !someExpression();
@@ -5180,7 +5180,7 @@ struct FormatStyle {
/// \version 9
bool SpaceAfterLogicalNot;
- /// If ``true``, a space will be inserted after the ``operator`` keyword.
+ /// If `true`, a space will be inserted after the `operator` keyword.
/// \code
/// true: false:
/// bool operator ==(int a); vs. bool operator==(int a);
@@ -5188,7 +5188,7 @@ struct FormatStyle {
/// \version 21
bool SpaceAfterOperatorKeyword;
- /// If \c true, a space will be inserted after the ``template`` keyword.
+ /// If \c true, a space will be inserted after the `template` keyword.
/// \code
/// true: false:
/// template <int> void foo(); vs. template<int> void foo();
@@ -5229,7 +5229,7 @@ struct FormatStyle {
/// \version 12
SpaceAroundPointerQualifiersStyle SpaceAroundPointerQualifiers;
- /// If ``false``, spaces will be removed before assignment operators.
+ /// If `false`, spaces will be removed before assignment operators.
/// \code
/// true: false:
/// int a = 5; vs. int a= 5;
@@ -5238,7 +5238,7 @@ struct FormatStyle {
/// \version 3.7
bool SpaceBeforeAssignmentOperators;
- /// If ``false``, spaces will be removed before case colon.
+ /// If `false`, spaces will be removed before case colon.
/// \code
/// true: false
/// switch (x) { vs. switch (x) {
@@ -5248,7 +5248,7 @@ struct FormatStyle {
/// \version 12
bool SpaceBeforeCaseColon;
- /// If ``true``, a space will be inserted before a C++11 braced list
+ /// If `true`, a space will be inserted before a C++11 braced list
/// used to initialize an object (after the preceding identifier or type).
/// \code
/// true: false:
@@ -5260,7 +5260,7 @@ struct FormatStyle {
/// \version 7
bool SpaceBeforeCpp11BracedList;
- /// If ``false``, spaces will be removed before constructor initializer
+ /// If `false`, spaces will be removed before constructor initializer
/// colon.
/// \code
/// true: false:
@@ -5269,7 +5269,7 @@ struct FormatStyle {
/// \version 7
bool SpaceBeforeCtorInitializerColon;
- /// If ``false``, spaces will be removed before enum underlying type colon.
+ /// If `false`, spaces will be removed before enum underlying type colon.
/// \code
/// true: false:
/// enum E : int {} enum E: int {}
@@ -5277,7 +5277,7 @@ struct FormatStyle {
/// \version 23
bool SpaceBeforeEnumUnderlyingTypeColon;
- /// If ``false``, spaces will be removed before inheritance colon.
+ /// If `false`, spaces will be removed before inheritance colon.
/// \code
/// true: false:
/// class Foo : Bar {} vs. class Foo: Bar {}
@@ -5285,8 +5285,8 @@ struct FormatStyle {
/// \version 7
bool SpaceBeforeInheritanceColon;
- /// If ``true``, a space will be added before a JSON colon. For other
- /// languages, e.g. JavaScript, use ``SpacesInContainerLiterals`` instead.
+ /// If `true`, a space will be added before a JSON colon. For other
+ /// languages, e.g. JavaScript, use `SpacesInContainerLiterals` instead.
/// \code
/// true: false:
/// { {
@@ -5298,12 +5298,12 @@ struct FormatStyle {
/// Different ways to put a space before opening parentheses.
enum SpaceBeforeParensStyle : int8_t {
- /// This is **deprecated** and replaced by ``Custom`` below, with all
- /// ``SpaceBeforeParensOptions`` but ``AfterPlacementOperator`` set to
- /// ``false``.
+ /// This is **deprecated** and replaced by `Custom` below, with all
+ /// `SpaceBeforeParensOptions` but `AfterPlacementOperator` set to
+ /// `false`.
SBPO_Never,
/// Put a space before opening parentheses only after control statement
- /// keywords (``for/if/while...``).
+ /// keywords (`for/if/while...`).
/// \code
/// void f() {
/// if (true) {
@@ -5312,10 +5312,10 @@ struct FormatStyle {
/// }
/// \endcode
SBPO_ControlStatements,
- /// Same as ``SBPO_ControlStatements`` except this option doesn't apply to
+ /// Same as `SBPO_ControlStatements` except this option doesn't apply to
/// ForEach and If macros. This is useful in projects where ForEach/If
/// macros are treated as function calls instead of control statements.
- /// ``SBPO_ControlStatementsExceptForEachMacros`` remains an alias for
+ /// `SBPO_ControlStatementsExceptForEachMacros` remains an alias for
/// backward compatibility.
/// \code
/// void f() {
@@ -5349,7 +5349,7 @@ struct FormatStyle {
/// \endcode
SBPO_Always,
/// Configure each individual space before parentheses in
- /// ``SpaceBeforeParensOptions``.
+ /// `SpaceBeforeParensOptions`.
SBPO_Custom,
};
@@ -5358,7 +5358,7 @@ struct FormatStyle {
SpaceBeforeParensStyle SpaceBeforeParens;
/// Precise control over the spacing before parentheses.
- /// \code
+ /// \code{.yaml}
/// # Should be declared this way:
/// SpaceBeforeParens: Custom
/// SpaceBeforeParensOptions:
@@ -5366,49 +5366,49 @@ struct FormatStyle {
/// AfterFunctionDefinitionName: true
/// \endcode
struct SpaceBeforeParensCustom {
- /// If ``true``, put space between control statement keywords
+ /// If `true`, put space between control statement keywords
/// (for/if/while...) and opening parentheses.
/// \code
/// true: false:
/// if (...) {} vs. if(...) {}
/// \endcode
bool AfterControlStatements;
- /// If ``true``, put space between foreach macros and opening parentheses.
+ /// If `true`, put space between foreach macros and opening parentheses.
/// \code
/// true: false:
/// FOREACH (...) vs. FOREACH(...)
/// <loop-body> <loop-body>
/// \endcode
bool AfterForeachMacros;
- /// If ``true``, put a space between function declaration name and opening
+ /// If `true`, put a space between function declaration name and opening
/// parentheses.
/// \code
/// true: false:
/// void f (); vs. void f();
/// \endcode
bool AfterFunctionDeclarationName;
- /// If ``true``, put a space between function definition name and opening
+ /// If `true`, put a space between function definition name and opening
/// parentheses.
/// \code
/// true: false:
/// void f () {} vs. void f() {}
/// \endcode
bool AfterFunctionDefinitionName;
- /// If ``true``, put space between if macros and opening parentheses.
+ /// If `true`, put space between if macros and opening parentheses.
/// \code
/// true: false:
/// IF (...) vs. IF(...)
/// <conditional-body> <conditional-body>
/// \endcode
bool AfterIfMacros;
- /// If ``true``, put a space between alternative operator ``not`` and the
+ /// If `true`, put a space between alternative operator `not` and the
/// opening parenthesis.
/// \code
/// true: false:
/// return not (a || b); vs. return not(a || b);
/// \endcode
bool AfterNot;
- /// If ``true``, put a space between operator overloading and opening
+ /// If `true`, put a space between operator overloading and opening
/// parentheses.
/// \code
/// true: false:
@@ -5416,7 +5416,7 @@ struct FormatStyle {
/// object.operator++ (10); object.operator++(10);
/// \endcode
bool AfterOverloadedOperator;
- /// If ``true``, put a space between operator ``new``/``delete`` and opening
+ /// If `true`, put a space between operator `new`/`delete` and opening
/// parenthesis.
/// \code
/// true: false:
@@ -5424,7 +5424,7 @@ struct FormatStyle {
/// delete (buf) T; delete(buf) T;
/// \endcode
bool AfterPlacementOperator;
- /// If ``true``, put space between requires keyword in a requires clause and
+ /// If `true`, put space between requires keyword in a requires clause and
/// opening parentheses, if there is one.
/// \code
/// true: false:
@@ -5433,7 +5433,7 @@ struct FormatStyle {
/// ... ...
/// \endcode
bool AfterRequiresInClause;
- /// If ``true``, put space between requires keyword in a requires expression
+ /// If `true`, put space between requires keyword in a requires expression
/// and opening parentheses.
/// \code
/// true: false:
@@ -5443,7 +5443,7 @@ struct FormatStyle {
/// } }
/// \endcode
bool AfterRequiresInExpression;
- /// If ``true``, put a space before opening parentheses only if the
+ /// If `true`, put a space before opening parentheses only if the
/// parentheses are not empty.
/// \code
/// true: false:
@@ -5478,7 +5478,7 @@ struct FormatStyle {
/// Control of individual space before parentheses.
///
- /// If ``SpaceBeforeParens`` is set to ``Custom``, use this to specify
+ /// If `SpaceBeforeParens` is set to `Custom`, use this to specify
/// how each individual space before parentheses case should be handled.
/// Otherwise, this is ignored.
/// \code{.yaml}
@@ -5491,8 +5491,8 @@ struct FormatStyle {
/// \version 14
SpaceBeforeParensCustom SpaceBeforeParensOptions;
- /// If ``true``, spaces will be before ``[``.
- /// Lambdas will not be affected. Only the first ``[`` will get a space added.
+ /// If `true`, spaces will be before `[`.
+ /// Lambdas will not be affected. Only the first `[` will get a space added.
/// \code
/// true: false:
/// int a [5]; vs. int a[5];
@@ -5501,7 +5501,7 @@ struct FormatStyle {
/// \version 10
bool SpaceBeforeSquareBrackets;
- /// If ``false``, spaces will be removed before range-based for loop
+ /// If `false`, spaces will be removed before range-based for loop
/// colon.
/// \code
/// true: false:
@@ -5510,7 +5510,7 @@ struct FormatStyle {
/// \version 7
bool SpaceBeforeRangeBasedForLoopColon;
- /// This option is **deprecated**. See ``Block`` of ``SpaceInEmptyBraces``.
+ /// This option is **deprecated**. See `Block` of `SpaceInEmptyBraces`.
/// \version 10
// bool SpaceInEmptyBlock;
@@ -5545,21 +5545,21 @@ struct FormatStyle {
/// Specifies when to insert a space in empty braces.
/// \note
/// This option doesn't apply to initializer braces if
- /// ``Cpp11BracedListStyle`` is not ``Block``.
+ /// `Cpp11BracedListStyle` is not `Block`.
/// \endnote
/// \version 22
SpaceInEmptyBracesStyle SpaceInEmptyBraces;
- /// If ``true``, spaces may be inserted into ``()``.
- /// This option is **deprecated**. See ``InEmptyParentheses`` of
- /// ``SpacesInParensOptions``.
+ /// If `true`, spaces may be inserted into `()`.
+ /// This option is **deprecated**. See `InEmptyParentheses` of
+ /// `SpacesInParensOptions`.
/// \version 3.7
// bool SpaceInEmptyParentheses;
/// The number of spaces before trailing line comments
- /// (``//`` - comments).
+ /// (`//` - comments).
///
- /// This does not affect trailing block comments (``/*`` - comments) as those
+ /// This does not affect trailing block comments (`/*` - comments) as those
/// commonly have
diff erent usage patterns and a number of special cases. In
/// the case of Verilog, it doesn't affect a comment right after the opening
/// parenthesis in the port or parameter list in a module header, because it
@@ -5576,38 +5576,38 @@ struct FormatStyle {
/// \version 3.7
unsigned SpacesBeforeTrailingComments;
- /// Styles for adding spacing after ``<`` and before ``>``
+ /// Styles for adding spacing after `<` and before `>`
/// in template argument lists.
enum SpacesInAnglesStyle : int8_t {
- /// Remove spaces after ``<`` and before ``>``.
+ /// Remove spaces after `<` and before `>`.
/// \code
/// static_cast<int>(arg);
/// std::function<void(int)> fct;
/// \endcode
SIAS_Never,
- /// Add spaces after ``<`` and before ``>``.
+ /// Add spaces after `<` and before `>`.
/// \code
/// static_cast< int >(arg);
/// std::function< void(int) > fct;
/// \endcode
SIAS_Always,
- /// Keep a single space after ``<`` and before ``>`` if any spaces were
- /// present. Option ``Standard: Cpp03`` takes precedence.
+ /// Keep a single space after `<` and before `>` if any spaces were
+ /// present. Option `Standard: Cpp03` takes precedence.
SIAS_Leave
};
/// The SpacesInAnglesStyle to use for template argument lists.
/// \version 3.4
SpacesInAnglesStyle SpacesInAngles;
- /// Styles for controlling spacing after ``/*`` and before ``*/`` in block
+ /// Styles for controlling spacing after `/*` and before `*/` in block
/// comments.
enum SpacesInBlockCommentsStyle : int8_t {
- /// Remove spaces after ``/*`` and before ``*/``.
+ /// Remove spaces after `/*` and before `*/`.
/// \code
/// /*comment*/
/// \endcode
SIBCS_Never,
- /// Add spaces after ``/*`` and before ``*/``.
+ /// Add spaces after `/*` and before `*/`.
/// \code
/// /* comment */
/// \endcode
@@ -5617,22 +5617,22 @@ struct FormatStyle {
};
/// The SpacesInBlockCommentsStyle to use for ordinary block comments.
- /// Documentation comments such as ``/** ... */`` and ``/*! ... */``
- /// and parameter comments ending with ``=`` before the closing ``*/`` are
+ /// Documentation comments such as `/** ... */` and `/*! ... */`
+ /// and parameter comments ending with `=` before the closing `*/` are
/// left unchanged.
/// \version 24
SpacesInBlockCommentsStyle SpacesInBlockComments;
- /// If ``true``, spaces will be inserted around if/for/switch/while
+ /// If `true`, spaces will be inserted around if/for/switch/while
/// conditions.
- /// This option is **deprecated**. See ``InConditionalStatements`` of
- /// ``SpacesInParensOptions``.
+ /// This option is **deprecated**. See `InConditionalStatements` of
+ /// `SpacesInParensOptions`.
/// \version 10
// bool SpacesInConditionalStatement;
- /// If ``true``, spaces are inserted inside container literals (e.g. ObjC and
+ /// If `true`, spaces are inserted inside container literals (e.g. ObjC and
/// Javascript array and dict literals). For JSON, use
- /// ``SpaceBeforeJsonColon`` instead.
+ /// `SpaceBeforeJsonColon` instead.
/// \code{.js}
/// true: false:
/// var arr = [ 1, 2, 3 ]; vs. var arr = [1, 2, 3];
@@ -5641,9 +5641,9 @@ struct FormatStyle {
/// \version 3.7
bool SpacesInContainerLiterals;
- /// If ``true``, spaces may be inserted into C style casts.
- /// This option is **deprecated**. See ``InCStyleCasts`` of
- /// ``SpacesInParensOptions``.
+ /// If `true`, spaces may be inserted into C style casts.
+ /// This option is **deprecated**. See `InCStyleCasts` of
+ /// `SpacesInParensOptions`.
/// \version 3.7
// bool SpacesInCStyleCastParentheses;
@@ -5656,7 +5656,7 @@ struct FormatStyle {
};
/// How many spaces are allowed at the start of a line comment. To disable the
- /// maximum set it to ``-1``, apart from that the maximum takes precedence
+ /// maximum set it to `-1`, apart from that the maximum takes precedence
/// over the minimum.
/// \code
/// Minimum = 1
@@ -5685,7 +5685,7 @@ struct FormatStyle {
/// /// - Bar /// - Bar
/// \endcode
///
- /// This option has only effect if ``ReflowComments`` is set to ``true``.
+ /// This option has only effect if `ReflowComments` is set to `true`.
/// \version 13
SpacesInLineComment SpacesInLineCommentPrefix;
@@ -5705,21 +5705,21 @@ struct FormatStyle {
SIPO_Custom,
};
- /// If ``true``, spaces will be inserted after ``(`` and before ``)``.
+ /// If `true`, spaces will be inserted after `(` and before `)`.
/// This option is **deprecated**. The previous behavior is preserved by using
- /// ``SpacesInParens`` with ``Custom`` and by setting all
- /// ``SpacesInParensOptions`` to ``true`` except for ``InCStyleCasts`` and
- /// ``InEmptyParentheses``.
+ /// `SpacesInParens` with `Custom` and by setting all
+ /// `SpacesInParensOptions` to `true` except for `InCStyleCasts` and
+ /// `InEmptyParentheses`.
/// \version 3.7
// bool SpacesInParentheses;
- /// Defines in which cases spaces will be inserted after ``(`` and before
- /// ``)``.
+ /// Defines in which cases spaces will be inserted after `(` and before
+ /// `)`.
/// \version 17
SpacesInParensStyle SpacesInParens;
/// Precise control over the spacing in parentheses.
- /// \code
+ /// \code{.yaml}
/// # Should be declared this way:
/// SpacesInParens: Custom
/// SpacesInParensOptions:
@@ -5740,7 +5740,7 @@ struct FormatStyle {
/// Uses the applicable option.
bool ExceptDoubleParentheses;
/// Put a space in parentheses only inside conditional statements
- /// (``for/if/while/switch...``).
+ /// (`for/if/while/switch...`).
/// \code
/// true: false:
/// if ( a ) { ... } vs. if (a) { ... }
@@ -5754,7 +5754,7 @@ struct FormatStyle {
/// y = (( int (*)(int) )foo)(x); y = ((int (*)(int))foo)(x);
/// \endcode
bool InCStyleCasts;
- /// Insert a space in empty parentheses, i.e. ``()``.
+ /// Insert a space in empty parentheses, i.e. `()`.
/// \code
/// true: false:
/// void f( ) { vs. void f() {
@@ -5797,7 +5797,7 @@ struct FormatStyle {
/// Control of individual spaces in parentheses.
///
- /// If ``SpacesInParens`` is set to ``Custom``, use this to specify
+ /// If `SpacesInParens` is set to `Custom`, use this to specify
/// how each individual space in parentheses case should be handled.
/// Otherwise, this is ignored.
/// \code{.yaml}
@@ -5811,7 +5811,7 @@ struct FormatStyle {
/// \version 17
SpacesInParensCustom SpacesInParensOptions;
- /// If ``true``, spaces will be inserted after ``[`` and before ``]``.
+ /// If `true`, spaces will be inserted after `[` and before `]`.
/// Lambdas without arguments or unspecified size array declarations will not
/// be affected.
/// \code
@@ -5828,11 +5828,11 @@ struct FormatStyle {
/// c++03 vs. vector<set<int> >
/// \endcode
///
- /// The correct way to spell a specific language version is e.g. ``c++11``.
- /// The historical aliases ``Cpp03`` and ``Cpp11`` are deprecated.
+ /// The correct way to spell a specific language version is e.g. `c++11`.
+ /// The historical aliases `Cpp03` and `Cpp11` are deprecated.
enum LanguageStandard : int8_t {
/// Parse and format as C++03.
- /// ``Cpp03`` is a deprecated alias for ``c++03``
+ /// `Cpp03` is a deprecated alias for `c++03`
LS_Cpp03, // c++03
/// Parse and format as C++11.
LS_Cpp11, // c++11
@@ -5847,7 +5847,7 @@ struct FormatStyle {
/// Parse and format as C++26.
LS_Cpp26, // c++26
/// Parse and format using the latest supported language version.
- /// ``Cpp11`` is a deprecated alias for ``Latest``
+ /// `Cpp11` is a deprecated alias for `Latest`
LS_Latest,
/// Automatic detection based on the input.
LS_Auto,
@@ -5901,7 +5901,7 @@ struct FormatStyle {
/// \endcode
///
/// makes the line break only occurs inside DAGArgs beginning with the
- /// specified identifiers ``ins`` and ``outs``.
+ /// specified identifiers `ins` and `outs`.
///
/// \code
/// let DAGArgIns = (ins
@@ -5949,7 +5949,7 @@ struct FormatStyle {
/// A vector of non-keyword identifiers that should be interpreted as template
/// names.
///
- /// A ``<`` after a template name is annotated as a template opener instead of
+ /// A `<` after a template name is annotated as a template opener instead of
/// a binary operator.
///
/// \version 20
@@ -5958,7 +5958,7 @@ struct FormatStyle {
/// A vector of non-keyword identifiers that should be interpreted as type
/// names.
///
- /// A ``*``, ``&``, or ``&&`` between a type name and another non-keyword
+ /// A `*`, `&`, or `&&` between a type name and another non-keyword
/// identifier is annotated as a pointer or reference token instead of a
/// binary operator.
///
@@ -5982,7 +5982,7 @@ struct FormatStyle {
/// \version 9
std::vector<std::string> TypenameMacros;
- /// This option is **deprecated**. See ``LF`` and ``CRLF`` of ``LineEnding``.
+ /// This option is **deprecated**. See `LF` and `CRLF` of `LineEnding`.
/// \version 10
// bool UseCRLF;
@@ -6010,7 +6010,7 @@ struct FormatStyle {
/// A vector of non-keyword identifiers that should be interpreted as variable
/// template names.
///
- /// A ``)`` after a variable template instantiation is **not** annotated as
+ /// A `)` after a variable template instantiation is **not** annotated as
/// the closing parenthesis of C-style cast operator.
///
/// \version 20
@@ -6072,7 +6072,7 @@ struct FormatStyle {
/// \endcode
WNBWELS_Always,
/// Keep existing newlines at the beginning and the end of namespace body.
- /// ``MaxEmptyLinesToKeep`` still applies.
+ /// `MaxEmptyLinesToKeep` still applies.
WNBWELS_Leave
};
@@ -6381,18 +6381,18 @@ FormatStyle getNoStyle();
/// Currently supported names: LLVM, Google, Chromium, Mozilla. Names are
/// compared case-insensitively.
///
-/// Returns ``true`` if the Style has been set.
+/// Returns `true` if the Style has been set.
bool getPredefinedStyle(StringRef Name, FormatStyle::LanguageKind Language,
FormatStyle *Style);
/// Parse configuration from YAML-formatted text.
///
-/// Style->Language is used to get the base style, if the ``BasedOnStyle``
+/// Style->Language is used to get the base style, if the `BasedOnStyle`
/// option is present.
///
/// The FormatStyleSet of Style is reset.
///
-/// When ``BasedOnStyle`` is not present, options not present in the YAML
+/// When `BasedOnStyle` is not present, options not present in the YAML
/// document, are retained in \p Style.
///
/// If AllowUnknownOptions is true, no errors are emitted if unknown
@@ -6417,8 +6417,8 @@ inline std::error_code parseConfiguration(StringRef Config, FormatStyle *Style,
/// Gets configuration in a YAML string.
std::string configurationAsText(const FormatStyle &Style);
-/// Returns the replacements necessary to sort all ``#include`` blocks
-/// that are affected by ``Ranges``.
+/// Returns the replacements necessary to sort all `#include` blocks
+/// that are affected by `Ranges`.
tooling::Replacements sortIncludes(const FormatStyle &Style, StringRef Code,
ArrayRef<tooling::Range> Ranges,
StringRef FileName,
@@ -6441,7 +6441,7 @@ formatReplacements(StringRef Code, const tooling::Replacements &Replaces,
/// * If a replacement has offset UINT_MAX, length 1, and a replacement text
/// that is the name of the header to be removed, the header will be removed
/// from \p Code if it exists.
-/// The include manipulation is done via ``tooling::HeaderInclude``, see its
+/// The include manipulation is done via `tooling::HeaderInclude`, see its
/// documentation for more details on how include insertion points are found and
/// what edits are produced.
Expected<tooling::Replacements>
@@ -6450,11 +6450,11 @@ cleanupAroundReplacements(StringRef Code, const tooling::Replacements &Replaces,
/// Represents the status of a formatting attempt.
struct FormattingAttemptStatus {
- /// A value of ``false`` means that any of the affected ranges were not
+ /// A value of `false` means that any of the affected ranges were not
/// formatted due to a non-recoverable syntax error.
bool FormatComplete = true;
- /// If ``FormatComplete`` is false, ``Line`` records a one-based
+ /// If `FormatComplete` is false, `Line` records a one-based
/// original line number at which a syntax error might have occurred. This is
/// based on a best-effort analysis and could be imprecise.
unsigned Line = 0;
@@ -6466,17 +6466,17 @@ struct FormattingAttemptStatus {
/// everything that might influence its formatting or might be influenced by its
/// formatting.
///
-/// Returns the ``Replacements`` necessary to make all \p Ranges comply with
+/// Returns the `Replacements` necessary to make all \p Ranges comply with
/// \p Style.
///
-/// If ``Status`` is non-null, its value will be populated with the status of
+/// If `Status` is non-null, its value will be populated with the status of
/// this formatting attempt. See \c FormattingAttemptStatus.
tooling::Replacements reformat(const FormatStyle &Style, StringRef Code,
ArrayRef<tooling::Range> Ranges,
StringRef FileName = "<stdin>",
FormattingAttemptStatus *Status = nullptr);
-/// Same as above, except if ``IncompleteFormat`` is non-null, its value
+/// Same as above, except if `IncompleteFormat` is non-null, its value
/// will be set to true if any of the affected ranges were not formatted due to
/// a non-recoverable syntax error.
tooling::Replacements reformat(const FormatStyle &Style, StringRef Code,
@@ -6486,14 +6486,14 @@ tooling::Replacements reformat(const FormatStyle &Style, StringRef Code,
/// Clean up any erroneous/redundant code in the given \p Ranges in \p
/// Code.
///
-/// Returns the ``Replacements`` that clean up all \p Ranges in \p Code.
+/// Returns the `Replacements` that clean up all \p Ranges in \p Code.
tooling::Replacements cleanup(const FormatStyle &Style, StringRef Code,
ArrayRef<tooling::Range> Ranges,
StringRef FileName = "<stdin>");
/// Fix namespace end comments in the given \p Ranges in \p Code.
///
-/// Returns the ``Replacements`` that fix the namespace comments in all
+/// Returns the `Replacements` that fix the namespace comments in all
/// \p Ranges in \p Code.
tooling::Replacements fixNamespaceEndComments(const FormatStyle &Style,
StringRef Code,
@@ -6504,7 +6504,7 @@ tooling::Replacements fixNamespaceEndComments(const FormatStyle &Style,
/// classes, structs, functions, namespaces, and enums in the given \p Ranges in
/// \p Code.
///
-/// Returns the ``Replacements`` that inserts or removes empty lines separating
+/// Returns the `Replacements` that inserts or removes empty lines separating
/// definition blocks in all \p Ranges in \p Code.
tooling::Replacements separateDefinitionBlocks(const FormatStyle &Style,
StringRef Code,
@@ -6514,46 +6514,46 @@ tooling::Replacements separateDefinitionBlocks(const FormatStyle &Style,
/// Sort consecutive using declarations in the given \p Ranges in
/// \p Code.
///
-/// Returns the ``Replacements`` that sort the using declarations in all
+/// Returns the `Replacements` that sort the using declarations in all
/// \p Ranges in \p Code.
tooling::Replacements sortUsingDeclarations(const FormatStyle &Style,
StringRef Code,
ArrayRef<tooling::Range> Ranges,
StringRef FileName = "<stdin>");
-/// Returns the ``LangOpts`` that the formatter expects you to set.
+/// Returns the `LangOpts` that the formatter expects you to set.
///
/// \param Style determines specific settings for lexing mode.
LangOptions getFormattingLangOpts(const FormatStyle &Style = getLLVMStyle());
-/// Description to be used for help text for a ``llvm::cl`` option for
+/// Description to be used for help text for a `llvm::cl` option for
/// specifying format style. The description is closely related to the operation
-/// of ``getStyle()``.
+/// of `getStyle()`.
extern const char *StyleOptionHelpDescription;
/// The suggested format style to use by default. This allows tools using
-/// ``getStyle`` to have a consistent default style.
+/// `getStyle` to have a consistent default style.
/// Different builds can modify the value to the preferred styles.
extern const char *DefaultFormatStyle;
-/// The suggested predefined style to use as the fallback style in ``getStyle``.
+/// The suggested predefined style to use as the fallback style in `getStyle`.
/// Different builds can modify the value to the preferred styles.
extern const char *DefaultFallbackStyle;
-/// Construct a FormatStyle based on ``StyleName``.
+/// Construct a FormatStyle based on `StyleName`.
///
-/// ``StyleName`` can take several forms:
+/// `StyleName` can take several forms:
/// * "{<key>: <value>, ...}" - Set specic style parameters.
/// * "<style name>" - One of the style names supported by getPredefinedStyle().
-/// * "file" - Load style configuration from a file called ``.clang-format``
-/// located in one of the parent directories of ``FileName`` or the current
-/// directory if ``FileName`` is empty.
+/// * "file" - Load style configuration from a file called `.clang-format`
+/// located in one of the parent directories of `FileName` or the current
+/// directory if `FileName` is empty.
/// * "file:<format_file_path>" to explicitly specify the configuration file to
/// use.
///
/// \param[in] StyleName Style name to interpret according to the description
/// above.
-/// \param[in] FileName Path to start search for .clang-format if ``StyleName``
+/// \param[in] FileName Path to start search for .clang-format if `StyleName`
/// == "file".
/// \param[in] FallbackStyle The name of a predefined style used to fallback to
/// in case \p StyleName is "file" and no file can be found.
@@ -6565,8 +6565,8 @@ extern const char *DefaultFallbackStyle;
/// emit a warning. If false, errors are emitted on unknown format
/// options.
///
-/// \returns FormatStyle as specified by ``StyleName``. If ``StyleName`` is
-/// "file" and no file is found, returns ``FallbackStyle``. If no style could be
+/// \returns FormatStyle as specified by `StyleName`. If `StyleName` is
+/// "file" and no file is found, returns `FallbackStyle`. If no style could be
/// determined, returns an Error.
Expected<FormatStyle>
getStyle(StringRef StyleName, StringRef FileName, StringRef FallbackStyle,
@@ -6574,11 +6574,11 @@ getStyle(StringRef StyleName, StringRef FileName, StringRef FallbackStyle,
bool AllowUnknownOptions = false,
llvm::SourceMgr::DiagHandlerTy DiagHandler = nullptr);
-// Guesses the language from the ``FileName`` and ``Code`` to be formatted.
+// Guesses the language from the `FileName` and `Code` to be formatted.
// Defaults to FormatStyle::LK_Cpp.
FormatStyle::LanguageKind guessLanguage(StringRef FileName, StringRef Code);
-// Returns a string representation of ``Language``.
+// Returns a string representation of `Language`.
inline StringRef getLanguageName(FormatStyle::LanguageKind Language) {
switch (Language) {
case FormatStyle::LK_C:
diff --git a/clang/include/clang/Tooling/Inclusions/IncludeStyle.h b/clang/include/clang/Tooling/Inclusions/IncludeStyle.h
index bf060617deec7..14273324b128a 100644
--- a/clang/include/clang/Tooling/Inclusions/IncludeStyle.h
+++ b/clang/include/clang/Tooling/Inclusions/IncludeStyle.h
@@ -18,9 +18,9 @@ namespace tooling {
/// Style for sorting and grouping C++ #include directives.
struct IncludeStyle {
- /// Styles for sorting multiple ``#include`` blocks.
+ /// Styles for sorting multiple `#include` blocks.
enum IncludeBlocksStyle {
- /// Sort each ``#include`` block separately.
+ /// Sort each `#include` block separately.
/// \code
/// #include "b.h" into #include "b.h"
///
@@ -28,7 +28,7 @@ struct IncludeStyle {
/// #include "a.h" #include <lib/main.h>
/// \endcode
IBS_Preserve,
- /// Merge multiple ``#include`` blocks together and sort as one.
+ /// Merge multiple `#include` blocks together and sort as one.
/// \code
/// #include "b.h" into #include "a.h"
/// #include "b.h"
@@ -36,9 +36,9 @@ struct IncludeStyle {
/// #include "a.h"
/// \endcode
IBS_Merge,
- /// Merge multiple ``#include`` blocks together and sort as one.
+ /// Merge multiple `#include` blocks together and sort as one.
/// Then split into groups based on category priority. See
- /// ``IncludeCategories``.
+ /// `IncludeCategories`.
/// \code
/// #include "b.h" into #include "a.h"
/// #include "b.h"
@@ -48,12 +48,12 @@ struct IncludeStyle {
IBS_Regroup,
};
- /// Dependent on the value, multiple ``#include`` blocks can be sorted
+ /// Dependent on the value, multiple `#include` blocks can be sorted
/// as one and divided based on category.
/// \version 6
IncludeBlocksStyle IncludeBlocks;
- /// See documentation of ``IncludeCategories``.
+ /// See documentation of `IncludeCategories`.
struct IncludeCategory {
/// The regular expression that this category matches.
std::string Regex;
@@ -69,35 +69,36 @@ struct IncludeStyle {
}
};
- /// Regular expressions denoting the
diff erent ``#include`` categories
- /// used for ordering ``#includes``.
+ /// Regular expressions denoting the
diff erent `#include` categories
+ /// used for ordering `#includes`.
///
- /// `POSIX extended
- /// <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html>`_
+ /// [POSIX
+ /// extended](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap09.html)
/// regular expressions are supported.
///
/// These regular expressions are matched against the filename of an include
/// (including the <> or "") in order. The value belonging to the first
- /// matching regular expression is assigned and ``#includes`` are sorted first
+ /// matching regular expression is assigned and `#includes` are sorted first
/// according to increasing category number and then alphabetically within
/// each category.
///
/// If none of the regular expressions match, INT_MAX is assigned as
/// category. The main header for a source file automatically gets category 0.
- /// so that it is generally kept at the beginning of the ``#includes``
- /// (https://llvm.org/docs/CodingStandards.html#include-style). However, you
- /// can also assign negative priorities if you have certain headers that
- /// always need to be first.
+ /// so that it is generally kept at the beginning of the `#includes`
+ /// (see [LLVM
+ /// style](https://llvm.org/docs/CodingStandards.html#include-style)).
+ /// However, you can also assign negative priorities if you have certain
+ /// headers that always need to be first.
///
- /// There is a third and optional field ``SortPriority`` which can used while
- /// ``IncludeBlocks = IBS_Regroup`` to define the priority in which
- /// ``#includes`` should be ordered. The value of ``Priority`` defines the
- /// order of ``#include blocks`` and also allows the grouping of ``#includes``
- /// of
diff erent priority. ``SortPriority`` is set to the value of
- /// ``Priority`` as default if it is not assigned.
+ /// There is a third and optional field `SortPriority` which can used while
+ /// `IncludeBlocks = IBS_Regroup` to define the priority in which
+ /// `#includes` should be ordered. The value of `Priority` defines the
+ /// order of `#include blocks` and also allows the grouping of `#includes`
+ /// of
diff erent priority. `SortPriority` is set to the value of
+ /// `Priority` as default if it is not assigned.
///
/// Each regular expression can be marked as case sensitive with the field
- /// ``CaseSensitive``, per default it is not.
+ /// `CaseSensitive`, per default it is not.
///
/// To configure this in the .clang-format file, use:
/// \code{.yaml}
@@ -123,10 +124,10 @@ struct IncludeStyle {
/// When guessing whether a #include is the "main" include (to assign
/// category 0, see above), use this regex of allowed suffixes to the header
/// stem. A partial match is done, so that:
- /// * ``""`` means "arbitrary suffix"
- /// * ``"$"`` means "no suffix"
+ /// * `""` means "arbitrary suffix"
+ /// * `"$"` means "no suffix"
///
- /// For example, if configured to ``"(_test)?$"``, then a header a.h would be
+ /// For example, if configured to `"(_test)?$"`, then a header a.h would be
/// seen as the "main" include in both a.cc and a_test.cc.
/// \version 3.9
std::string IncludeIsMainRegex;
@@ -136,27 +137,27 @@ struct IncludeStyle {
/// file-to-main-include mapping.
///
/// By default, clang-format considers files as "main" only when they end
- /// with: ``.c``, ``.cc``, ``.cpp``, ``.c++``, ``.cxx``, ``.m`` or ``.mm``
+ /// with: `.c`, `.cc`, `.cpp`, `.c++`, `.cxx`, `.m` or `.mm`
/// extensions.
/// For these files a guessing of "main" include takes place
/// (to assign category 0, see above). This config option allows for
/// additional suffixes and extensions for files to be considered as "main".
///
- /// For example, if this option is configured to ``(Impl\.hpp)$``,
- /// then a file ``ClassImpl.hpp`` is considered "main" (in addition to
- /// ``Class.c``, ``Class.cc``, ``Class.cpp`` and so on) and "main
+ /// For example, if this option is configured to `(Impl\.hpp)$`,
+ /// then a file `ClassImpl.hpp` is considered "main" (in addition to
+ /// `Class.c`, `Class.cc`, `Class.cpp` and so on) and "main
/// include file" logic will be executed (with *IncludeIsMainRegex* setting
/// also being respected in later phase). Without this option set,
- /// ``ClassImpl.hpp`` would not have the main include file put on top
+ /// `ClassImpl.hpp` would not have the main include file put on top
/// before any other include.
/// \version 10
std::string IncludeIsMainSourceRegex;
/// Character to consider in the include directives for the main header.
enum MainIncludeCharDiscriminator : int8_t {
- /// Main include uses quotes: ``#include "foo.hpp"`` (the default).
+ /// Main include uses quotes: `#include "foo.hpp"` (the default).
MICD_Quote,
- /// Main include uses angle brackets: ``#include <foo.hpp>``.
+ /// Main include uses angle brackets: `#include <foo.hpp>`.
MICD_AngleBracket,
/// Main include uses either quotes or angle brackets.
MICD_Any
More information about the cfe-commits
mailing list