[docs][clang-format] use yaml types style

[FederAndInk]

Summary

Use yaml types for clang-format documentation (String, Integer, List of Strings, ...) instead of c++ types

track generated plurals in a file

Fix typo in clang/Format/Format.h

[MyDeveloperDay]

Thank you for your submission, but...

1. This is not the way to change this file, its autogenerated from clang/include/Format/Format.h using clang/docs/tools/dump_format_style.py
2. Why do you think it should be std::string? To be honest this file pretty much describes the YAML file format of .clang-format so actually I would suggest it saying string was more correct

I think the main problem is options like this:

Here we say its a std::vector<RawStringFormat> which doesn't really tell you much, as its actually just a YAML array of RawStringFormat records without actually telling you what a RawStringFormat record contains

RawStringFormats:
  - Language: TextProto
      Delimiters:
        - 'pb'
        - 'proto'
      EnclosingFunctions:
        - 'PARSE_TEXT_PROTO'
      BasedOnStyle: google
  - Language: Cpp
      Delimiters:
        - 'cc'
        - 'cpp'
      BasedOnStyle: llvm
      CanonicalDelimiter: 'cc'

So whilst I see that you were being consistent I kind of feel its in the wrong direction, we should be moving away from using C++ names here but more explaining what the YAML should look like.

Alas the C++ in Format.h is important because the types are needed because we are generating the documentation directly from the code. But in most of places we are using an enumeration like this one.

we are not saying clang::FormatStyle::RefernceAlignmentStyle and I'm not convinced we'd want to

I hope that helps, but thank you for the patch.

[FederAndInk]

Thank you for your explanations, I understand now.

But as I look into clang/docs/tools/dump_format_style.py I see that it does not entirely generate clang/docs/ClangFormatStyleOptions.rst it replaces the lines between {START,END}_FORMAT_STYLE_OPTIONS

I understand your point, but as of now, the inconsistency comes from the part that is not auto-generated, are you suggesting editing dump_format_style.py to have simpler types such as string? Then how should we replace std::vector? Something like Type[] e.g. string[]?

Or maybe we should first include BasedOnStyle into dump_format_style.py. Then take care of how to render types?

What do you suggest? I am genuinely asking, as I really don't know what would be the best way to do things. Maybe we should include other people? I don't really know who to add as reviewers for that, but I think, the way to show types, should be discussed?

As for detailing RawStringFormat, it wasn't the purpose of this patch, and maybe it should have its own?

[MyDeveloperDay]

In D108765#2967363, @FederAndInk wrote:

Thank you for your explanations, I understand now.

But as I look into clang/docs/tools/dump_format_style.py I see that it does not entirely generate clang/docs/ClangFormatStyleOptions.rst it replaces the lines between {START,END}_FORMAT_STYLE_OPTIONS

I understand your point, but as of now, the inconsistency comes from the part that is not auto-generated, are you suggesting editing dump_format_style.py to have simpler types such as string? Then how should we replace std::vector? Something like Type[] e.g. string[]?

Or maybe we should first include BasedOnStyle into dump_format_style.py. Then take care of how to render types?

What do you suggest? I am genuinely asking, as I really don't know what would be the best way to do things. Maybe we should include other people? I don't really know who to add as reviewers for that, but I think, the way to show types, should be discussed?

As for detailing RawStringFormat, it wasn't the purpose of this patch, and maybe it should have its own?

You are correct the file isn't 100% generated and some of it comes from another .h file too.

But now we have you interesting in making a contribution which you clearly are lets think about how we might do this.

To hook into the clang-format team I always recommend adding the #clang-format project, (which I added to this review), but also I recommend passing the review via @krasimir , @HazardyKnusperkeks , @curdeius there are some others who are here often like @owenpan and @sammccall and of course @klimek (who started all this). Please also of course add me @MyDeveloperDay I try to check the reviews daily as one of my frustrations was not being able to get things reviewed so I try to be pretty active.

From my perspective I do like the idea of substituting out the std::string and std::vector for something like string[] how about we start with something simple like trying to fix the cases for AttributeMacros (std::vector<std::string>) maybe with just simple substitution.

We can pass that via the rest of the team and see what they feel.

AttributeMacros (in configuration string[])

or something like that, I'm not convinced anyone is using this documentation to know its a std::vector!

[HazardyKnusperkeks]

As the one who wrote that:

1. Yes that part is not auto generated, because it is not in the format.h.
2. I'm more in favor of removing the std:: from the documentation.
3. It is for the YAML documentation, then stick with the YAML names: List of Strings is my proposal.

[FederAndInk]

What about: unsigned? And enum or struct types such as BracketAlignmentStyle, ArrayInitializerAlignmentStyle, ...? Should we add something like: Enum BracketAlignmentStyle and Dictionnary BraceWrapping?

The complete list:

53 bool                              -> Boolean
18 unsigned                          -> ?
9 std::vector<std::string>           -> List of Strings
5 std::string                        -> String
4 AlignConsecutiveStyle              -> ?
2 int                                -> Integer
1 UseTabStyle                        -> ?
1 TrailingCommaStyle                 -> ?
1 string                             -> String
1 std::vector<RawStringFormat>       -> ?
1 std::vector<IncludeCategory>       -> ?...
1 SpacesInLineComment
1 SpacesInAnglesStyle
1 SpaceBeforeParensOptions
1 SpaceAroundPointerQualifiersStyle
1 SortJavaStaticImportOptions
1 SortIncludesOptions
1 ShortLambdaStyle
1 ShortIfStyle
1 ShortFunctionStyle
1 ShortBlockStyle
1 ReturnTypeBreakingStyle
1 ReferenceAlignmentStyle
1 PPDirectiveIndentStyle
1 PointerAlignmentStyle
1 OperandAlignmentStyle
1 NamespaceIndentationKind
1 LanguageStandard
1 LanguageKind
1 LambdaBodyIndentationKind
1 JavaScriptQuoteStyle
1 IndentExternBlockStyle
1 IncludeBlocksStyle
1 EscapedNewlineAlignmentStyle
1 EmptyLineBeforeAccessModifierStyle
1 EmptyLineAfterAccessModifierStyle
1 DefinitionReturnTypeBreakingStyle
1 BreakTemplateDeclarationsStyle
1 BreakInheritanceListStyle
1 BreakConstructorInitializersStyle
1 BracketAlignmentStyle
1 BraceWrappingFlags
1 BraceBreakingStyle
1 BitFieldColonSpacingStyle
1 BinPackStyle
1 BinaryOperatorStyle
1 ArrayInitializerAlignmentStyle

[MyDeveloperDay]

I'm good with words like List of Strings but I don't think we need Enum

unsigned I think Integer, I'm not sure what the code is even going to do if you supply a -ve, Warn I hope! (there's contribution idea number 2 for you right there!) ;-)

[FederAndInk]

Ok, well, the reason I proposed this patch in the first place was that I have been working on a .clang-format schema (https://json-schema.org/) :) and I spotted the inconsistency. I checked, and clang-format reports an error if we give a negative value to an option expecting an unsigned. In the schema I am able to specify a minimum and I think it's appropriate to give the information to the user that it expect a positive/unsigned integer, what do you think?

Also, interesting question, how do we want to handle plural, as the formulation 'List of Types' introduces it. If we do it manually, it won't scale. We could include a dependency in python to something like inflect. I'll upload a new patch soon.

[FederAndInk]

Use yaml type style for clang-format documentation (String, Integer, List of Strings, ...) instead of c++ types.

Fix typo in clang/Format/Format.h

Regenarate ClangFormatStyleOptions.rst

[FederAndInk]

For now, I handle plural manually, but it can be changed, I also kept Unsigned, what are your thoughts?

Thanks for being so kind and responsive, it's really great to work on that :) as it is my first contribution to clang.

[MyDeveloperDay]

LGTM, thanks for adding that and fixing the spelling mistake, let the others have time to chip in.

[MyDeveloperDay]

In D108765#2969036, @FederAndInk wrote:

For now, I handle plural manually, but it can be changed, I also kept Unsigned, what are your thoughts?

I think thats ok for now, did you try building the file with sphinx-build, I run

`/usr/bin/sphinx-build -n ./docs ./html`

Then go and look at the html

Thanks for being so kind and responsive, it's really great to work on that :) as it is my first contribution to clang.

That is how it should be right ;-).

I assume you don't have commit access, we'll need your name and email address if you want one of us to land it, so we can accredit you with the contribution, but if you think you might like to work on some other things, it might be worth get ting the  "getting commit access" process started.

I think its always good to wait to give others some chance to comment before we commit, as we are all in different timezones.

[FederAndInk]

look at the html

Done, thanks

I assume you don't have commit access, we'll need your name and email address

Here it is: Ludovic Jozeau <[e-mail]> it should also be on my profile

but if you think you might like to work on some other things, it might be worth get ting the "getting commit access" process started.

Yeah, after reading https://llvm.org/docs/DeveloperPolicy.html#obtaining-commit-access, I think I'll wait until I do another contribution. :)

I think its always good to wait to give others some chance to comment before we commit, as we are all in different timezones.

Ok, that's fine.

[HazardyKnusperkeks]

Looks good and I agree with the choices.

clang/docs/tools/dump_format_style.py

35

Could you not just check if there is a y at the end and replace it with ies, otherweise add an s?

[FederAndInk]

clang/docs/tools/dump_format_style.py

35

Well, I thought about it, but then what about: whish -> whishes, leaf -> leaves, ... and irregulars? That's why I brought up the idea about using python inflect. Do you think it's enough for now to replace y -> ies and put an 's' to the others?

[HazardyKnusperkeks]

clang/docs/tools/dump_format_style.py

35

I'm okay with either way, in both cases there comes a time where someone must pay attention to add something here. We just have to look carefully in the review.

[MyDeveloperDay]

clang/docs/tools/dump_format_style.py

35

it would be nice if in the event of a missing plural it complained.

[HazardyKnusperkeks]

clang/docs/tools/dump_format_style.py

35

But that would mean we have to add each plural here. So every new list, which is not of strings, would most likely also needed to be added here. I think that is too much, but then again there are not that much lists, so maybe it's worth the work.

[FederAndInk]

Ok, here is my proposal for plurals, I have some ideas, I think the safest/most complete would be to have a file tracking generated plurals and tell the user of the script to check newly generated plurals then add them to git, this would also allow reviewers to see new plurals generated. I'll put the updated revision of my idea soon.

Another idea without tracking plurals would be to show the list of generated word -> plural but I think it would add noise over time and wouldn't add value, but if we don't want to add a plurals.txt file in git it would be a possibility.

And again, I don't really understand if we are allowed or not to pull in a dependency such as pluralizer or inflect, this would be another idea

[FederAndInk]

generate plurals, for now supporting -y ending (-y to -ies/-ys), track generated plurals and show new ones to be checked

[MyDeveloperDay]

clang/docs/tools/dump_format_style.py

33

This failed for me with invalid syntax

[FederAndInk]

clang/docs/tools/dump_format_style.py

33

Oh, ok, sorry, I might be using to recent python features, I'll remove type specifier, what is the recommended python version to use?

[HazardyKnusperkeks]

In D108765#2972159, @FederAndInk wrote:

And again, I don't really understand if we are allowed or not to pull in a dependency such as pluralizer or inflect, this would be another idea

My Python knowledge is very limited, but if it runs out of the box, or with very limited required user action with a reasonably new Python (if Python 2 can be reasonably new is another question), I think it would be fine.

clang/docs/tools/dump_format_style.py

10

I think these should be sorted.

18

So you would add a plurals.txt in git and make the change visible through git diff? What about just reordering? I.e. Strings is on line 2, but after a change in line 1. Maybe sort the output?

I'm not against this procedure, but also not in favor. :)

33

Oh, ok, sorry, I might be using to recent python features, I'll remove type specifier, what is the recommended python version to use?

That I can not answer. I run

$ python --version
Python 3.9.5

[FederAndInk]

clang/docs/tools/dump_format_style.py

33

Ok thanks, this is a reasonably recent version, I think we might want to explicitly specify python3 in the script to avoid using python2, I'll upload the diffs immediately.

[FederAndInk]

clang/docs/tools/dump_format_style.py

10

ok, it will be done

18

This line is used to restore the version of plurals.txt to HEAD, so when calling the script multiple times, it keeps showing new plurals until plurals.txt gets committed.

So you would add a plurals.txt in git and make the change visible through git diff?

yes, that's it

What about just reordering?

I don't think we want ordering, it is ordered from first plural generated to last/new one, so git diff will only show new plurals

[FederAndInk]

add common plural rules, use python3 explicitly, reorder imports

[MyDeveloperDay]

clang/docs/tools/dump_format_style.py

10

are these standard imports or are we going to have to pip install something?

18

I'm personally not in favour of this script calling back to git

[MyDeveloperDay]

error: pathspec './plurals.txt' did not match any file(s) known to git
Traceback (most recent call last):
  File "./dump_format_style.py", line 18, in <module>
    subprocess.check_call(['git', 'checkout', '--', PLURAL_FILE])
  File "/usr/lib/python3.8/subprocess.py", line 364, in check_call
    raise CalledProcessError(retcode, cmd)
subprocess.CalledProcessError: Command '['git', 'checkout', '--', './plurals.txt']' returned non-zero exit status 1.

[FederAndInk]

In D108765#2974153, @MyDeveloperDay wrote:

error: pathspec './plurals.txt' did not match any file(s) known to git
Traceback (most recent call last):
  File "./dump_format_style.py", line 18, in <module>
    subprocess.check_call(['git', 'checkout', '--', PLURAL_FILE])
  File "/usr/lib/python3.8/subprocess.py", line 364, in check_call
    raise CalledProcessError(retcode, cmd)
subprocess.CalledProcessError: Command '['git', 'checkout', '--', './plurals.txt']' returned non-zero exit status 1.

This is expected if plurals.txt is not in git yet, there is call that will do nothing on errors, but I use check_call to report errors from git checkout -- plurals.txt. To test, you can either replace temporarily the check_call by a call in clang/docs/tools/dump_format_style.py:18 or get the commit/create a temporary commit with plurals.txt

Maybe to simplify the testing/review procedure, I'll change check_call by call and if it is accepted, change it back to the checked version.

clang/docs/tools/dump_format_style.py

10

These are all standard imports, no worries :) (https://docs.python.org/3/library/subprocess.html)

otherwise, I would have directly used python inflect/or any other package to solve the plural problem

18

Well, I was inspired by other python scripts in the llvm-project repo that use subprocess to call git, it just touches the plurals.txt files to allow the user calling the script multiple times and be warned of the new plurals each time until it is committed. We could do without it, but we would lose a part of automation and the user of the script would have to partly manage the plurals.txt file.

A semi-solution I see is to at least tell the user to use git checkout -- plurals.txt if they want to clean up plurals/regenerate them and see which ones are new and/or call git diff -- plurals.txt to show new plurals which may be less "problematic" than git checkout -- plurals.txt. What do you think?

Tl;dr of solutions:

1. reconsider as this technic is in use in other scripts in llvm-project
2. call git diff instead of git checkout leading to less consistent and precise messages
3. just tell the user what are their options (printing 'you can use git checkout -- plurals.txt or git diff -- plurals.txt'...)
4. other ideas?

[FederAndInk]

use correct python assignment from tuple, ask the user if they want to invoke git, use call instead of check_call to allow testing

[HazardyKnusperkeks]

From my point we can try that one, if there are problems we have plenty of time to revert it.

[FederAndInk]

clang/docs/tools/dump_format_style.py

21–25

Just to let you know, I've made modifications to be able to test the code with an untracked plurals file. We might want stricter checks by calling check_call instead, also we won't need line 22 above.

[MyDeveloperDay]

I think interacting with git or even blocking for input doesn’t feel right

I have an issue out on llvm-premerge-checks that would run this tool and that couldn’t block like this

[MyDeveloperDay]

For me it feels enough to output to stderr that we are missing plurals and what they are for, it’s not like you can say what they should be is it? This will happen so infrequently that it’s not worth the environment issues that checking git will cause.

[FederAndInk]

remove git invocation and user input, tell the user what the plurals are used for

[FederAndInk]

Ok, so I removed git invocation and I tell the user what are their options, at least warnings are emitted for new plurals, and they will be shown in git status/diff and in revisions.

[MyDeveloperDay]

Could you just rebase, I'm not getting a clean merge of ClangFormatStyleOptions.rst

you are missing the changes from D108752: [clang-format] Group options that pack constructor initializers

[FederAndInk]

rebase main

[MyDeveloperDay]

clang/docs/tools/dump_format_style.py

18

printing this is just unnecessary please remove

[FederAndInk]

clang/docs/tools/dump_format_style.py

18

Ok, should I also remove line 18?

[FederAndInk]

remove one print l17, tell me if we don't want the second print (now l17)

fixed typo in the script coment -> comment

[MyDeveloperDay]

I still think the printing is unnecessary, tell me when the plurals will be different otherwise keep quiet? otherwise, it confuses people making them think they have to do something

[FederAndInk]

only print info on generated plurals if there is a new plural

[FederAndInk]

@MyDeveloperDay is it all good? I'm sorry for all the misunderstanding,

[FederAndInk]

Thanks for the merge, I now understand more how this all works and what we want from these scripts.

[FederAndInk]

Also, don't we want to change the title and summary of the commit/revision? Because it does not reflect the real changes now in the repo

clang/docs/ClangFormatStyleOptions.rst

 =================================
 
 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``).
 
 
-**BasedOnStyle** (``string``)
+**BasedOnStyle** (``String``)
   The style used for all options not specifically set in the configuration.
 
   This option is supported only in the :program:`clang-format` configuration
   (both within ``-style='{...}'`` and the ``.clang-format`` file).
 
   Possible values:
 
   * ``LLVM``
* ``InheritParentConfig``
     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}``
 
 .. START_FORMAT_STYLE_OPTIONS
 
-**AccessModifierOffset** (``int``)
+**AccessModifierOffset** (``Integer``)
   The extra indent or outdent of access modifiers, e.g. ``public:``.
 
 **AlignAfterOpenBracket** (``BracketAlignmentStyle``)
   If ``true``, horizontally aligns arguments after an open bracket.
 
   This applies to round brackets (parentheses), angle brackets and square
   brackets.
 
* ``OAS_AlignAfterOperator`` (in configuration: ``AlignAfterOperator``)
 
     .. code-block:: c++
 
       int aaa = bbbbbbbbbbbbbbb
               + ccccccccccccccc;
 
 
 
-**AlignTrailingComments** (``bool``)
+**AlignTrailingComments** (``Boolean``)
   If ``true``, aligns trailing comments.
 
   .. code-block:: c++
 
     true:                                   false:
     int a;     // My comment a      vs.     int a; // My comment a
     int b = 2; // comment  b                int b = 2; // comment about b
 
-**AllowAllArgumentsOnNextLine** (``bool``)
+**AllowAllArgumentsOnNextLine** (``Boolean``)
   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++
 
     true:
     callFunction(
         a, b, c, d);
 
     false:
     callFunction(a,
                  b,
                  c,
                  d);
 
-**AllowAllConstructorInitializersOnNextLine** (``bool``)
+**AllowAllConstructorInitializersOnNextLine** (``Boolean``)
   If a constructor definition with a member initializer list doesn't
   fit on a single line, allow putting all member initializers onto the next
   line, if ```ConstructorInitializerAllOnOneLineOrOnePerLine``` is true.
   Note that this parameter has no effect if
   ```ConstructorInitializerAllOnOneLineOrOnePerLine``` is false.
 
   .. code-block:: c++
 
     true:
     MyClass::MyClass() :
         member0(0), member1(2) {}
 
     false:
     MyClass::MyClass() :
         member0(0),
         member1(2) {}
 
-**AllowAllParametersOfDeclarationOnNextLine** (``bool``)
+**AllowAllParametersOfDeclarationOnNextLine** (``Boolean``)
   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 ``false``.
 
   .. code-block:: c++
 
     true:
     void myFunction(
* ``SBS_Always`` (in configuration: ``Always``)
 
     .. code-block:: c++
 
       while (true) {}
       while (true) { continue; }
 
 
 
-**AllowShortCaseLabelsOnASingleLine** (``bool``)
+**AllowShortCaseLabelsOnASingleLine** (``Boolean``)
   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;
                                             }
 
-**AllowShortEnumsOnASingleLine** (``bool``)
+**AllowShortEnumsOnASingleLine** (``Boolean``)
   Allow short enums on a single line.
 
   .. code-block:: c++
 
     true:
     enum { A, B } myEnum;
 
     false:
* ``SLS_All`` (in configuration: ``All``)
 
     .. code-block:: c++
 
       auto lambda = [](int a) {}
       auto lambda2 = [](int a) { return a; };
 
 
 
-**AllowShortLoopsOnASingleLine** (``bool``)
+**AllowShortLoopsOnASingleLine** (``Boolean``)
   If ``true``, ``while (true) continue;`` can be put on a single
   line.
 
 **AlwaysBreakAfterDefinitionReturnType** (``DefinitionReturnTypeBreakingStyle``)
   The function definition return type breaking style to use.  This
   option is **deprecated** and is retained for backwards compatibility.
 
   Possible values:
.. code-block:: c++
       int f();
       int
       f() {
         return 1;
       }
 
 
 
-**AlwaysBreakBeforeMultilineStrings** (``bool``)
+**AlwaysBreakBeforeMultilineStrings** (``Boolean``)
   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.
 
   .. code-block:: c++
.. code-block:: c++
        }
        template <typename T>
        T foo(int aaaaaaaaaaaaaaaaaaaaa,
              int bbbbbbbbbbbbbbbbbbbbb) {
        }
 
 
 
-**AttributeMacros** (``std::vector<std::string>``)
+**AttributeMacros** (``List of Strings``)
   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) __ununsed;
     void only_writes_to_buffer(char *__output buffer);
 
   In the .clang-format configuration file, this can be configured like:
 
   .. code-block:: yaml
 
     AttributeMacros: ['__capability', '__output', '__ununsed']
 
-**BinPackArguments** (``bool``)
+**BinPackArguments** (``Boolean``)
   If ``false``, a function call's arguments will either be all on the
   same line or will have one line each.
 
   .. code-block:: c++
 
     true:
     void f() {
       f(aaaaaaaaaaaaaaaaaaaa, aaaaaaaaaaaaaaaaaaaa,
         aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
     }
 
     false:
     void f() {
       f(aaaaaaaaaaaaaaaaaaaa,
         aaaaaaaaaaaaaaaaaaaa,
         aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa);
     }
 
-**BinPackParameters** (``bool``)
+**BinPackParameters** (``Boolean``)
   If ``false``, a function declaration's or function definition's
   parameters will either all be on the same line or will have one line each.
 
   .. code-block:: c++
 
     true:
     void f(int aaaaaaaaaaaaaaaaaaaa, int aaaaaaaaaaaaaaaaaaaa,
            int aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) {}
* ``bool SplitEmptyNamespace`` If ``false``, empty namespace body can be put on a single line.
 
     .. code-block:: c++
 
       namespace Foo   vs.  namespace Foo
       {}                   {
                            }
 
 
-**BreakAfterJavaFieldAnnotations** (``bool``)
+**BreakAfterJavaFieldAnnotations** (``Boolean``)
   Break after each annotation on a field in Java files.
 
   .. code-block:: java
 
      true:                                  false:
      @Partial                       vs.     @Partial @Mock DataLoad loader;
      @Mock
      DataLoad loader;
.. code-block:: c++
       void bar() { foo(true); }
       } // namespace N
 
   * ``BS_Custom`` (in configuration: ``Custom``)
     Configure each individual brace in `BraceWrapping`.
 
 
 
-**BreakBeforeConceptDeclarations** (``bool``)
+**BreakBeforeConceptDeclarations** (``Boolean``)
   If ``true``, concept will be placed on a new line.
 
   .. code-block:: c++
 
     true:
      template<typename T>
      concept ...
 
     false:
      template<typename T> concept ...
 
-**BreakBeforeTernaryOperators** (``bool``)
+**BreakBeforeTernaryOperators** (``Boolean``)
   If ``true``, ternary operators will be placed after line breaks.
 
   .. code-block:: c++
 
      true:
      veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription
          ? firstValue
          : SecondValueVeryVeryVeryVeryLong;
* ``BILS_AfterComma`` (in configuration: ``AfterComma``)
     .. code-block:: c++
 
        class Foo : Base1,
                    Base2
        {};
 
 
 
-**BreakStringLiterals** (``bool``)
+**BreakStringLiterals** (``Boolean``)
   Allow breaking string literals when formatting.
 
   .. code-block:: c++
 
      true:
      const char* x = "veryVeryVeryVeryVeryVe"
                      "ryVeryVeryVeryVeryVery"
                      "VeryLongString";
 
      false:
      const char* x =
        "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString";
 
-**ColumnLimit** (``unsigned``)
+**ColumnLimit** (``Unsigned``)
   The column limit.
 
   A column limit of ``0`` means that there is no column limit. In this case,
   clang-format will respect the input's line breaking decisions within
   statements unless they contradict other rules.
 
-**CommentPragmas** (``std::string``)
+**CommentPragmas** (``String``)
   A regular expression that describes comments with special meaning,
   which should not be split into lines or otherwise changed.
 
   .. code-block:: c++
 
      // CommentPragmas: '^ FOOBAR pragma:'
      // Will leave the following line unaffected
      #include <vector> // FOOBAR pragma: keep
 
-**CompactNamespaces** (``bool``)
+**CompactNamespaces** (``Boolean``)
   If ``true``, consecutive namespace declarations will be on the same
   line. If ``false``, each namespace is declared on a new line.
 
   .. code-block:: c++
 
     true:
     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++
 
     namespace Foo { namespace Bar {
     namespace Extra {
     }}}
 
-**ConstructorInitializerAllOnOneLineOrOnePerLine** (``bool``)
+**ConstructorInitializerAllOnOneLineOrOnePerLine** (``Boolean``)
   If the constructor initializers don't fit on a line, put each
   initializer on its own line.
 
   .. code-block:: c++
 
     true:
     SomeClass::Constructor()
         : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) {
       return 0;
     }
 
     false:
     SomeClass::Constructor()
         : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa),
           aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) {
       return 0;
     }
 
-**ConstructorInitializerIndentWidth** (``unsigned``)
+**ConstructorInitializerIndentWidth** (``Unsigned``)
   The number of characters to use for indentation of constructor
   initializer lists as well as inheritance lists.
 
-**ContinuationIndentWidth** (``unsigned``)
+**ContinuationIndentWidth** (``Unsigned``)
   Indent width for line continuations.
 
   .. code-block:: c++
 
      ContinuationIndentWidth: 2
 
      int i =         //  VeryVeryVeryVeryVeryLongComment
        longFunction( // Again a long comment
          arg);
 
-**Cpp11BracedListStyle** (``bool``)
+**Cpp11BracedListStyle** (``Boolean``)
   If ``true``, format braced lists as best suited for C++11 braced
   lists.
 
   Important differences:
   - No spaces inside the braced list.
   - No line break before the closing brace.
   - Indentation with the continuation indent, not with the block indent.
 
   Fundamentally, C++11 braced lists are formatted exactly like function
   calls would be formatted in their place. If the braced list follows a name
   (e.g. a type or variable name), clang-format formats as if the ``{}`` were
   the parentheses of a function call with that name. If there is no name,
   a zero-length name is assumed.
 
   .. code-block:: c++
 
      true:                                  false:
      vector<int> x{1, 2, 3, 4};     vs.     vector<int> x{ 1, 2, 3, 4 };
      vector<T> x{{}, {}, {}, {}};           vector<T> x{ {}, {}, {}, {} };
      f(MyMap[{composite, key}]);            f(MyMap[{ composite, key }]);
      new int[3]{1, 2, 3};                   new int[3]{ 1, 2, 3 };
 
-**DeriveLineEnding** (``bool``)
+**DeriveLineEnding** (``Boolean``)
   Analyze the formatted file for the most used line ending (``\r\n``
   or ``\n``). ``UseCRLF`` is only used as a fallback if none can be derived.
 
-**DerivePointerAlignment** (``bool``)
+**DerivePointerAlignment** (``Boolean``)
   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.
 
-**DisableFormat** (``bool``)
+**DisableFormat** (``Boolean``)
   Disables formatting completely.
 
 **EmptyLineAfterAccessModifier** (``EmptyLineAfterAccessModifierStyle``)
   Defines when to put an empty line after access modifiers.
   ``EmptyLineBeforeAccessModifier`` configuration handles the number of
   empty lines between two access modifiers.
 
   Possible values:
.. code-block:: c++
 
       private:
 
       protected:
       };
 
 
 
-**ExperimentalAutoDetectBinPacking** (``bool``)
+**ExperimentalAutoDetectBinPacking** (``Boolean``)
   If ``true``, clang-format detects whether function calls and
   definitions are formatted with one parameter per line.
 
   Each call can be bin-packed, one-per-line or inconclusive. If it is
   inconclusive, e.g. completely on one line, but a decision needs to be
   made, clang-format analyzes whether there are other bin-packed cases in
   the input file and act accordingly.
 
   NOTE: This is an experimental flag, that might go away or be renamed. Do
   not use this in config files, etc. Use at your own risk.
 
-**FixNamespaceComments** (``bool``)
+**FixNamespaceComments** (``Boolean``)
   If ``true``, clang-format adds missing namespace end comments for
   short namespaces and fixes invalid existing ones. Short ones are
   controlled by "ShortNamespaceLines".
 
   .. code-block:: c++
 
      true:                                  false:
      namespace a {                  vs.     namespace a {
      foo();                                 foo();
      bar();                                 bar();
      } // namespace a                       }
 
-**ForEachMacros** (``std::vector<std::string>``)
+**ForEachMacros** (``List of Strings``)
   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>
 
   In the .clang-format configuration file, this can be configured like:
 
   .. code-block:: yaml
 
     ForEachMacros: ['RANGES_FOR', 'FOREACH']
 
   For example: BOOST_FOREACH.
 
-**IfMacros** (``std::vector<std::string>``)
+**IfMacros** (``List of Strings``)
   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(...)
.. code-block:: c++
 
        #include "b.h"               into      #include "a.h"
                                               #include "b.h"
        #include <lib/main.h>
        #include "a.h"                         #include <lib/main.h>
 
 
 
-**IncludeCategories** (``std::vector<IncludeCategory>``)
+**IncludeCategories** (``List of IncludeCategories``)
   Regular expressions denoting the different ``#include`` categories
   used for ordering ``#includes``.
 
   `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
IncludeCategories:
       - Regex:           '^(<|"(gtest|gmock|isl|json)/)'
         Priority:        3
       - Regex:           '<[[:alnum:].]+>'
         Priority:        4
       - Regex:           '.*'
         Priority:        1
         SortPriority:    0
 
-**IncludeIsMainRegex** (``std::string``)
+**IncludeIsMainRegex** (``String``)
   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"
 
   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** (``std::string``)
+**IncludeIsMainSourceRegex** (``String``)
   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``
   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
   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
   before any other include.
 
-**IndentAccessModifiers** (``bool``)
+**IndentAccessModifiers** (``Boolean``)
   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
   consequence, record members are always indented 2 levels below the record,
   regardless of the access modifier presence. Value of the
class C {                      vs.     class C {
        };                                       };
      public:                                  public:
        C();                                     C();
      };                                     };
      void foo() {                           void foo() {
        return 1;                              return 1;
      }                                      }
 
-**IndentCaseBlocks** (``bool``)
+**IndentCaseBlocks** (``Boolean``)
   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** (``bool``)
+**IndentCaseLabels** (``Boolean``)
   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++
* ``IEBS_Indent`` (in configuration: ``Indent``)
     .. code-block:: c++
 
         extern "C" {
           void foo();
         }
 
 
 
-**IndentGotoLabels** (``bool``)
+**IndentGotoLabels** (``Boolean``)
   Indent goto labels.
 
   When ``false``, goto labels are flushed left.
 
   .. code-block:: c++
 
      true:                                  false:
      int f() {                      vs.     int f() {
.. code-block:: c++
        #if FOO
          #if BAR
            #include <foo>
          #endif
        #endif
 
 
 
-**IndentRequires** (``bool``)
+**IndentRequires** (``Boolean``)
   Indent the requires clause in a template
 
   .. code-block:: 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) {
        //....
      }
 
-**IndentWidth** (``unsigned``)
+**IndentWidth** (``Unsigned``)
   The number of columns to use for indentation.
 
   .. code-block:: c++
 
      IndentWidth: 3
 
      void f() {
         someFunction();
         if (true, false) {
            f();
         }
      }
 
-**IndentWrappedFunctionNames** (``bool``)
+**IndentWrappedFunctionNames** (``Boolean``)
   Indent if a function definition or declaration is wrapped after the
   type.
 
   .. code-block:: c++
 
      true:
      LoooooooooooooooooooooooooooooooooooooooongReturnType
          LoooooooooooooooooooooooooooooooongFunctionDeclaration();
* ``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
     that a container should be formatted one-per-line (i.e. not bin-packed).
     So inserting a trailing comma counteracts bin-packing.
 
 
 
-**JavaImportGroups** (``std::vector<std::string>``)
+**JavaImportGroups** (``List of Strings``)
   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``.
* ``JSQS_Double`` (in configuration: ``Double``)
 
     .. code-block:: js
 
        string1 = "foo";
        string2 = "bar";
 
 
 
-**JavaScriptWrapImports** (``bool``)
+**JavaScriptWrapImports** (``Boolean``)
   Whether to wrap JavaScript import/export statements.
 
   .. code-block:: js
 
      true:
      import {
          VeryLongImportsAreAnnoying,
          VeryLongImportsAreAnnoying,
          VeryLongImportsAreAnnoying,
      } from 'some/module.js'
 
      false:
      import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js"
 
-**KeepEmptyLinesAtTheStartOfBlocks** (``bool``)
+**KeepEmptyLinesAtTheStartOfBlocks** (``Boolean``)
   If true, the empty line at the start of blocks is kept.
 
   .. code-block:: c++
 
      true:                                  false:
      if (foo) {                     vs.     if (foo) {
                                               bar();
        bar();                               }
* ``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/).
 
 
 
-**MacroBlockBegin** (``std::string``)
+**MacroBlockBegin** (``String``)
   A regular expression matching macros that start a block.
 
   .. code-block:: c++
 
      # With:
      MacroBlockBegin: "^NS_MAP_BEGIN|\
      NS_TABLE_HEAD$"
      MacroBlockEnd: "^\
.. code-block:: c++
      NS_MAP_BEGIN
      foo();
      NS_MAP_END
 
      NS_TABLE_HEAD
      bar();
      NS_TABLE_FOO_END
 
-**MacroBlockEnd** (``std::string``)
+**MacroBlockEnd** (``String``)
   A regular expression matching macros that end a block.
 
-**MaxEmptyLinesToKeep** (``unsigned``)
+**MaxEmptyLinesToKeep** (``Unsigned``)
   The maximum number of consecutive empty lines to keep.
 
   .. code-block:: c++
 
      MaxEmptyLinesToKeep: 1         vs.     MaxEmptyLinesToKeep: 0
      int f() {                              int f() {
        int = 1;                                 int i = 1;
                                                 i = foo();
.. code-block:: c++
          int i;
          namespace in {
            int i;
          }
        }
 
 
 
-**NamespaceMacros** (``std::vector<std::string>``)
+**NamespaceMacros** (``List of Strings``)
   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>
**ObjCBinPackProtocolList** (``BinPackStyle``)
   * ``BPS_Always`` (in configuration: ``Always``)
     Always bin-pack parameters.
 
   * ``BPS_Never`` (in configuration: ``Never``)
     Never bin-pack parameters.
 
 
 
-**ObjCBlockIndentWidth** (``unsigned``)
+**ObjCBlockIndentWidth** (``Unsigned``)
   The number of characters to use for indentation of ObjC blocks.
 
   .. code-block:: objc
 
      ObjCBlockIndentWidth: 4
 
      [operation setCompletionBlock:^{
          [self onOperationDone];
      }];
 
-**ObjCBreakBeforeNestedBlockParam** (``bool``)
+**ObjCBreakBeforeNestedBlockParam** (``Boolean``)
   Break parameters list into lines when there is nested block
   parameters in a function call.
 
   .. code-block:: 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;
              }]
      }
 
-**ObjCSpaceAfterProperty** (``bool``)
+**ObjCSpaceAfterProperty** (``Boolean``)
   Add a space after ``@property`` in Objective-C, i.e. use
   ``@property (readonly)`` instead of ``@property(readonly)``.
 
-**ObjCSpaceBeforeProtocolList** (``bool``)
+**ObjCSpaceBeforeProtocolList** (``Boolean``)
   Add a space in front of an Objective-C protocol list, i.e. use
   ``Foo <Protocol>`` instead of ``Foo<Protocol>``.
 
-**PPIndentWidth** (``int``)
+**PPIndentWidth** (``Integer``)
   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++
 
      PPIndentWidth: 1
 
      #ifdef __linux__
      # define FOO
      #else
      # define BAR
      #endif
 
-**PenaltyBreakAssignment** (``unsigned``)
+**PenaltyBreakAssignment** (``Unsigned``)
   The penalty for breaking around an assignment operator.
 
-**PenaltyBreakBeforeFirstCallParameter** (``unsigned``)
+**PenaltyBreakBeforeFirstCallParameter** (``Unsigned``)
   The penalty for breaking a function call after ``call(``.
 
-**PenaltyBreakComment** (``unsigned``)
+**PenaltyBreakComment** (``Unsigned``)
   The penalty for each line break introduced inside a comment.
 
-**PenaltyBreakFirstLessLess** (``unsigned``)
+**PenaltyBreakFirstLessLess** (``Unsigned``)
   The penalty for breaking before the first ``<<``.
 
-**PenaltyBreakString** (``unsigned``)
+**PenaltyBreakString** (``Unsigned``)
   The penalty for each line break introduced inside a string literal.
 
-**PenaltyBreakTemplateDeclaration** (``unsigned``)
+**PenaltyBreakTemplateDeclaration** (``Unsigned``)
   The penalty for breaking after template declaration.
 
-**PenaltyExcessCharacter** (``unsigned``)
+**PenaltyExcessCharacter** (``Unsigned``)
   The penalty for each character outside of the column limit.
 
-**PenaltyIndentedWhitespace** (``unsigned``)
+**PenaltyIndentedWhitespace** (``Unsigned``)
   Penalty for each character of whitespace indentation
   (counted relative to leading non-whitespace column).
 
-**PenaltyReturnTypeOnItsOwnLine** (``unsigned``)
+**PenaltyReturnTypeOnItsOwnLine** (``Unsigned``)
   Penalty for putting the return type of a function onto its own
   line.
 
 **PointerAlignment** (``PointerAlignmentStyle``)
   Pointer and reference alignment style.
 
   Possible values:
 
* ``PAS_Middle`` (in configuration: ``Middle``)
     Align pointer in the middle.
 
     .. code-block:: c++
 
       int * a;
 
 
 
-**RawStringFormats** (``std::vector<RawStringFormat>``)
+**RawStringFormats** (``List of RawStringFormats``)
   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
* ``RAS_Middle`` (in configuration: ``Middle``)
     Align reference in the middle.
 
     .. code-block:: c++
 
       int & a;
 
 
 
-**ReflowComments** (``bool``)
+**ReflowComments** (``Boolean``)
   If ``true``, clang-format will attempt to re-flow comments.
 
   .. code-block:: c++
 
      false:
      // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
      /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
 
      true:
      // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
      // information
      /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
       * information */
 
-**ShortNamespaceLines** (``unsigned``)
+**ShortNamespaceLines** (``Unsigned``)
   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
   end comments for those.
 
* ``SJSIO_After`` (in configuration: ``After``)
     .. code-block:: java
 
       import org.example.ClassA;
 
       import static org.example.function1;
 
 
 
-**SortUsingDeclarations** (``bool``)
+**SortUsingDeclarations** (``Boolean``)
   If ``true``, clang-format will sort using declarations.
 
   The order of using declarations is defined as follows:
   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++
 
      false:                                 true:
      using std::cout;               vs.     using std::cin;
      using std::cin;                        using std::cout;
 
-**SpaceAfterCStyleCast** (``bool``)
+**SpaceAfterCStyleCast** (``Boolean``)
   If ``true``, a space is inserted after C style casts.
 
   .. code-block:: c++
 
      true:                                  false:
      (int) i;                       vs.     (int)i;
 
-**SpaceAfterLogicalNot** (``bool``)
+**SpaceAfterLogicalNot** (``Boolean``)
   If ``true``, a space is inserted after the logical not operator (``!``).
 
   .. code-block:: c++
 
      true:                                  false:
      ! someExpression();            vs.     !someExpression();
 
-**SpaceAfterTemplateKeyword** (``bool``)
+**SpaceAfterTemplateKeyword** (``Boolean``)
   If ``true``, a space will be inserted after the 'template' keyword.
 
   .. code-block:: c++
 
      true:                                  false:
      template <int> void foo();     vs.     template<int> void foo();
 
 **SpaceAroundPointerQualifiers** (``SpaceAroundPointerQualifiersStyle``)
* ``SAPQ_Both`` (in configuration: ``Both``)
 
     .. code-block:: c++
 
        PointerAlignment: Left                 PointerAlignment: Right
        void* const * x = NULL;         vs.     void * const *x = NULL;
 
 
 
-**SpaceBeforeAssignmentOperators** (``bool``)
+**SpaceBeforeAssignmentOperators** (``Boolean``)
   If ``false``, spaces will be removed before assignment operators.
 
   .. code-block:: c++
 
      true:                                  false:
      int a = 5;                     vs.     int a= 5;
      a += 42;                               a+= 42;
 
-**SpaceBeforeCaseColon** (``bool``)
+**SpaceBeforeCaseColon** (``Boolean``)
   If ``false``, spaces will be removed before case colon.
 
   .. code-block:: c++
 
     true:                                   false
     switch (x) {                    vs.     switch (x) {
       case 1 : break;                         case 1: break;
     }                                       }
 
-**SpaceBeforeCpp11BracedList** (``bool``)
+**SpaceBeforeCpp11BracedList** (``Boolean``)
   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++
 
      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** (``bool``)
+**SpaceBeforeCtorInitializerColon** (``Boolean``)
   If ``false``, spaces will be removed before constructor initializer
   colon.
 
   .. code-block:: c++
 
      true:                                  false:
      Foo::Foo() : a(a) {}                   Foo::Foo(): a(a) {}
 
-**SpaceBeforeInheritanceColon** (``bool``)
+**SpaceBeforeInheritanceColon** (``Boolean``)
   If ``false``, spaces will be removed before inheritance colon.
 
   .. code-block:: c++
 
      true:                                  false:
      class Foo : Bar {}             vs.     class Foo: Bar {}
 
 **SpaceBeforeParens** (``SpaceBeforeParensOptions``)
.. code-block:: c++
        void f () {
          if (true) {
            f ();
          }
        }
 
 
 
-**SpaceBeforeRangeBasedForLoopColon** (``bool``)
+**SpaceBeforeRangeBasedForLoopColon** (``Boolean``)
   If ``false``, spaces will be removed before range-based for loop
   colon.
 
   .. code-block:: c++
 
      true:                                  false:
      for (auto v : values) {}       vs.     for(auto v: values) {}
 
-**SpaceBeforeSquareBrackets** (``bool``)
+**SpaceBeforeSquareBrackets** (``Boolean``)
   If ``true``, spaces will be before  ``[``.
   Lambdas will not be affected. Only the first ``[`` will get a space added.
 
   .. code-block:: c++
 
      true:                                  false:
      int a [5];                    vs.      int a[5];
      int a [5][5];                 vs.      int a[5][5];
 
-**SpaceInEmptyBlock** (``bool``)
+**SpaceInEmptyBlock** (``Boolean``)
   If ``true``, spaces will be inserted into ``{}``.
 
   .. code-block:: c++
 
      true:                                false:
      void f() { }                   vs.   void f() {}
      while (true) { }                     while (true) {}
 
-**SpaceInEmptyParentheses** (``bool``)
+**SpaceInEmptyParentheses** (``Boolean``)
   If ``true``, spaces may be inserted into ``()``.
 
   .. code-block:: c++
 
      true:                                false:
      void f( ) {                    vs.   void f() {
        int x[] = {foo( ), bar( )};          int x[] = {foo(), bar()};
        if (true) {                          if (true) {
          f( );                                f();
        }                                    }
      }                                    }
 
-**SpacesBeforeTrailingComments** (``unsigned``)
+**SpacesBeforeTrailingComments** (``Unsigned``)
   The number of spaces before trailing line comments
   (``//`` - comments).
 
   This does not affect trailing block comments (``/*`` - comments) as
   those commonly have different usage patterns and a number of special
   cases.
 
   .. code-block:: c++
.. code-block:: c++
        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.
 
 
 
-**SpacesInCStyleCastParentheses** (``bool``)
+**SpacesInCStyleCastParentheses** (``Boolean``)
   If ``true``, spaces may be inserted into C style casts.
 
   .. code-block:: c++
 
      true:                                  false:
      x = ( int32 )y                 vs.     x = (int32)y
 
-**SpacesInConditionalStatement** (``bool``)
+**SpacesInConditionalStatement** (``Boolean``)
   If ``true``, spaces will be inserted around if/for/switch/while
   conditions.
 
   .. code-block:: c++
 
      true:                                  false:
      if ( a )  { ... }              vs.     if (a) { ... }
      while ( i < 5 )  { ... }               while (i < 5) { ... }
 
-**SpacesInContainerLiterals** (``bool``)
+**SpacesInContainerLiterals** (``Boolean``)
   If ``true``, spaces are inserted inside container literals (e.g.
   ObjC and Javascript array and dict literals).
 
   .. code-block:: 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});
**SpacesInLineCommentPrefix** (``SpacesInLineComment``)
   Nested configuration flags:
 
 
   * ``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.
 
 
-**SpacesInParentheses** (``bool``)
+**SpacesInParentheses** (``Boolean``)
   If ``true``, spaces will be inserted after ``(`` and before ``)``.
 
   .. code-block:: c++
 
      true:                                  false:
      t f( Deleted & ) & = delete;   vs.     t f(Deleted &) & = delete;
 
-**SpacesInSquareBrackets** (``bool``)
+**SpacesInSquareBrackets** (``Boolean``)
   If ``true``, spaces will be inserted after ``[`` and before ``]``.
   Lambdas without arguments or unspecified size array declarations will not
   be affected.
 
   .. code-block:: c++
 
      true:                                  false:
      int a[ 5 ];                    vs.     int a[5];
* ``LS_Latest`` (in configuration: ``Latest``)
     Parse and format using the latest supported language version.
     ``Cpp11`` is a deprecated alias for ``Latest``
 
   * ``LS_Auto`` (in configuration: ``Auto``)
     Automatic detection based on the input.
 
 
 
-**StatementAttributeLikeMacros** (``std::vector<std::string>``)
+**StatementAttributeLikeMacros** (``List of Strings``)
   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++
 
     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.
 
-**StatementMacros** (``std::vector<std::string>``)
+**StatementMacros** (``List of Strings``)
   A vector of macros that should be interpreted as complete
   statements.
 
   Typical macros are expressions, and require a semi-colon to be
   added; sometimes this is not the case, and this allows to make
   clang-format aware of such cases.
 
   For example: Q_UNUSED
 
-**TabWidth** (``unsigned``)
+**TabWidth** (``Unsigned``)
   The number of columns used for tab stops.
 
-**TypenameMacros** (``std::vector<std::string>``)
+**TypenameMacros** (``List of Strings``)
   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(...)
 
   In the .clang-format configuration file, this can be configured like:
 
   .. code-block:: yaml
 
     TypenameMacros: ['STACK_OF', 'LIST']
 
   For example: OpenSSL STACK_OF, BSD LIST_ENTRY.
 
-**UseCRLF** (``bool``)
+**UseCRLF** (``Boolean``)
   Use ``\r\n`` instead of ``\n`` for line breaks.
   Also used as fallback if ``DeriveLineEnding`` is true.
 
 **UseTab** (``UseTabStyle``)
   The way to use tab characters in the resulting file.
 
   Possible values:
 
* ``UT_AlignWithSpaces`` (in configuration: ``AlignWithSpaces``)
     alignment.
 
   * ``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.
 
 
 
-**WhitespaceSensitiveMacros** (``std::vector<std::string>``)
+**WhitespaceSensitiveMacros** (``List of Strings``)
   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(...)

clang/docs/tools/dump_format_style.py

-#!/usr/bin/env python
+#!/usr/bin/env python3
 # A tool to parse the FormatStyle struct from Format.h and update the
 # documentation in ../ClangFormatStyleOptions.rst automatically.
 # Run from the directory in which this file is located to update the docs.
 
 import collections
+import inspect
 import os
 import re
+import subprocess
 
 CLANG_DIR = os.path.join(os.path.dirname(__file__), '../..')
 FORMAT_STYLE_FILE = os.path.join(CLANG_DIR, 'include/clang/Format/Format.h')
 INCLUDE_STYLE_FILE = os.path.join(CLANG_DIR, 'include/clang/Tooling/Inclusions/IncludeStyle.h')
 DOC_FILE = os.path.join(CLANG_DIR, 'docs/ClangFormatStyleOptions.rst')
 
+PLURAL_FILE = os.path.join(os.path.dirname(__file__), 'plurals.txt')
+
+clean_plurals = input('Reset plurals file (to reemit warnings)? [y/N] ')
+if clean_plurals.lower() == 'y':
+  # To allow testing with an untracked PLURAL_FILE
+  open(PLURAL_FILE, 'w').close() # TODO: remove this line when review is accepted
+  # TODO: use check_call when review is accepted
+  subprocess.call(['git', 'checkout', '--', PLURAL_FILE])
+
+plurals = set(open(PLURAL_FILE).read().splitlines())
 
 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
 
+def register_plural(singular: str, plural: str):
+  if plural not in plurals:
+    plurals.add(plural)
+    open(PLURAL_FILE, 'a').write(plural + '\n')
+    cf = inspect.currentframe()
+    lineno = ''
+    if cf and cf.f_back:
+      lineno = ':' + str(cf.f_back.f_lineno)
+    print(f'{__file__}{lineno} check if plural of {singular} is {plural}')
+  return plural
+
+def pluralize(word: str):
+  lword = word.lower()
+  if len(lword) >= 2 and lword[-1] == 'y' and lword[-2] not in 'aeiou':
+    return register_plural(word, word[:-1] + 'ies')
+  elif lword.endswith(('s', 'sh', 'ch', 'x', 'z')):
+    return register_plural(word, word[:-1] + 'es')
+  elif lword.endswith('fe'):
+    return register_plural(word, word[:-2] + 'ves')
+  elif lword.endswith('f') and not lword.endswith('ff'):
+    return register_plural(word, word[:-1] + 'ves')
+  else:
+    return register_plural(word, word + 's')
+
+
+def to_yaml_type(typestr: str):
+  if typestr == 'bool':
+    return 'Boolean'
+  elif typestr == 'int':
+    return 'Integer'
+  elif typestr == 'unsigned':
+    return 'Unsigned'
+  elif typestr == 'std::string':
+    return 'String'
+  
+  subtype, napplied = re.subn(r'^std::vector<(.*)>$', r'\1', typestr)
+  if napplied == 1:
+    return 'List of ' + pluralize(to_yaml_type(subtype))
+
+  return typestr
+
 def doxygen2rst(text):
   text = re.sub(r'<tt>\s*(.*?)\s*<\/tt>', r'``\1``', text)
   text = re.sub(r'\\c ([^ ,;\.]+)', r'``\1``', text)
   text = re.sub(r'\\\w+ ', '', text)
   return text
 
 def indent(text, columns, indent_first_line=True):
   indent = ' ' * columns
   s = re.sub(r'\n([^\n])', '\n' + indent + '\\1', text, flags=re.S)
   if not indent_first_line or s.startswith('\n'):
     return s
   return indent + s
 
 class Option(object):
   def __init__(self, name, type, comment):
     self.name = name
     self.type = type
     self.comment = comment.strip()
     self.enum = None
     self.nested_struct = None
 
   def __str__(self):
-    s = '**%s** (``%s``)\n%s' % (self.name, self.type,
+    s = '**%s** (``%s``)\n%s' % (self.name, to_yaml_type(self.type),
                                  doxygen2rst(indent(self.comment, 2)))
     if self.enum and self.enum.values:
       s += indent('\n\nPossible values:\n\n%s\n' % self.enum, 2)
     if self.nested_struct:
       s += indent('\n\nNested configuration flags:\n\n%s\n' %self.nested_struct,
                   2)
     return s
 

 class NestedEnum(object):
   def __init__(self, name, enumtype, comment, values):
     self.name = name
     self.comment = comment
     self.values = values
     self.type = enumtype
 
   def __str__(self):
-    s = '\n* ``%s %s``\n%s' % (self.type, self.name,
+    s = '\n* ``%s %s``\n%s' % (to_yaml_type(self.type), self.name,
                                  doxygen2rst(indent(self.comment, 2)))
     s += indent('\nPossible values:\n\n', 2)
     s += indent('\n'.join(map(str, self.values)),2)
     return s;
 
 class EnumValue(object):
   def __init__(self, name, comment, config):
     self.name = name

clang/docs/tools/plurals.txt

+Strings
+IncludeCategories
+RawStringFormats

clang/include/clang/Format/Format.h

enum SpaceBeforeParensOptions : unsigned char {
     ///      }
     ///    }
     /// \endcode
     SBPO_ControlStatements,
     /// 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
-    /// backward compatability.
+    /// backward compatibility.
     /// \code
     ///    void f() {
     ///      Q_FOREACH(...) {
     ///        f();
     ///      }
     ///    }
     /// \endcode
     SBPO_ControlStatementsExceptControlMacros,