[clang-format][doc] SortIncludes documentation: remove contradiction in its description

[michael-g-matthews]

Summary

The style option SortIncludes contains a contradiction between its initial description and the list of possible values.

Currently the description incorrectly states:

If CaseInsensitive, includes are sorted in an ASCIIbetical or case insensitive fashion. If CaseSensitive, includes are sorted in an alphabetical or case sensitive fashion

And the possible values section correctly states:

SI_CaseSensitive (in configuration: CaseSensitive) Includes are sorted in an ASCIIbetical or case sensitive fashion.
SI_CaseInsensitive (in configuration: CaseInsensitive) Includes are sorted in an alphabetical or case insensitive fashion

This patch shortens the initial description to read:

Controls if and how clang-format will sort #includes.

This removes the contradiction and ensures there is only a singular explanation for how this style option works.

Fixes https://github.com/llvm/llvm-project/issues/62033.

[rymiel]

NOTE: Clang-Format Team Automated Review Comment

Your review contains a change to ClangFormatStyleOptions.rst but not a change to clang/include/clang/Format/Format.h

ClangFormatStyleOptions.rst is auto generated from Format.h via clang/docs/tools/dump_format_style.py, please run this to regenerate the .rst

You can validate that the rst is valid by running.

./docs/tools/dump_format_style.py
mkdir -p html
/usr/bin/sphinx-build -n ./docs ./html

NOTE: Clang-Format Team Automated Review Comment

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

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

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

[michael-g-matthews]

Amended commit to include change to clang/include/clang/Format/Format.h

[MyDeveloperDay]

Sorry I don’t get how this change helps. Removing the option values doesn’t make it clearer IMHO

[HazardyKnusperkeks]

In D147894#4254941, @MyDeveloperDay wrote:

Sorry I don’t get how this change helps. Removing the option values does make it clearer IMHO

What options?

[michael-g-matthews]

I am also a little confused by what you mean @MyDeveloperDay. The options that were removed contained incorrect documentation (listing ASCIIbetical as CaseInsensitive). The enum documentation immediately after was however correct, so the documentation was self-contradictory. Instead of removing the options, I could have just fixed the typo, but then you have redundant documentation. In that case, if there are changes in the future, a dev will have to make documentation changes in two places instead of one. In my opinion, this was the cleaner fix, but I am willing to acquiesce if fixing the typo is preferable

[MyDeveloperDay]

Yes I didn’t see them repeated below

[michael-g-matthews]

If this is considered fully approved, would someone with commit access be able to commit this on my behalf? This is my first contribution so I do not have access. My name and email are Mike Matthews and [e-mail]. Thank you!

clang/docs/ClangFormatStyleOptions.rst

* ``BBCDS_Never`` (in configuration: ``Never``)
 
     .. code-block:: c++
 
       template <typename T> concept C = ...;
 
   * ``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.
+    penalities.
 
   * ``BBCDS_Always`` (in configuration: ``Always``)
     Always break before ``concept``, putting it in the line after the
     template declaration.
 
     .. code-block:: c++
 
       template <typename T>
namespace b {                      namespace b {
        int foo;                           int foo;
        int bar;                           int bar;
      } // namespace b                   } // namespace b
 
 .. _SortIncludes:
 
 **SortIncludes** (``SortIncludesOptions``) :versionbadge:`clang-format 3.8` :ref:`¶ <SortIncludes>`
   Controls if and how clang-format will sort ``#includes``.
-  If ``Never``, includes are never sorted.
-  If ``CaseInsensitive``, includes are sorted in an ASCIIbetical or case
-  insensitive fashion.
-  If ``CaseSensitive``, includes are sorted in an alphabetical or case
-  sensitive fashion.
 
   Possible values:
 
   * ``SI_Never`` (in configuration: ``Never``)
     Includes are never sorted.
 
     .. code-block:: c++
 

clang/include/clang/Format/Format.h

enum SortIncludesOptions : int8_t {
     ///    #include "a/b.h"
     ///    #include "B/A.h"
     ///    #include "B/a.h"
     /// \endcode
     SI_CaseInsensitive,
   };
 
   /// Controls if and how clang-format will sort ``#includes``.
-  /// If ``Never``, includes are never sorted.
-  /// If ``CaseInsensitive``, includes are sorted in an ASCIIbetical or case
-  /// insensitive fashion.
-  /// If ``CaseSensitive``, includes are sorted in an alphabetical or case
-  /// sensitive fashion.
   /// \version 3.8
   SortIncludesOptions SortIncludes;
 
   /// Position for Java Static imports.
   enum SortJavaStaticImportOptions : int8_t {
     /// Static imports are placed before non-static imports.
     /// \code{.java}
     ///   import static org.example.function1;