[clang-format] [docs] [NFC] improve clarity in the QualifierAlignment warning

[MyDeveloperDay]

Summary

Improve the clarity and guidance of the warning when using code modifying option in clang-format see D69764: [clang-format] Add Left/Right Const fixer capability

[curdeius]

LGTM with typos fixed.

clang/include/clang/Format/Format.h

1903

[MyDeveloperDay]

clang/include/clang/Format/Format.h

1903

Sorry that's my dyslexia kicking in! thanks for the pointers.

[simon.giesecke]

clang/include/clang/Format/Format.h

1902

I don't think incorrect code generation is the decisive point here (or at least the wording is confusing if "code generation" refers to the output of clang-format rather than, what I would understand, the binary code generated by the compiler). Rather it's that the semantics of the source code might change. Whether that causes syntax errors, bad code generation, or remains without any visible effect is probably impossible to judge here.

1903

As discussed around https://reviews.llvm.org/D69764#3032727, I see how macros could break this.

But what exactly does "especially" mean here, with respect to cases not involving macros?

Does it mean:

• We have some indication that this might break even without macros.
• We have no such indication but want to play safe until this has been tested in the wild.
• We can never know for sure...

At least in the last case, I'd suggest to remove the word "especially". That's true for all options of clang-format...

Similarly in the second case. That's true for all newly introduced options of clang-format.

In the first case, it makes sense to keep the word. But some more specific indication of the potential issues with and without macros seem to be helpful.

[MyDeveloperDay]

Try and improve the wordage

[MyDeveloperDay]

We have no such indication but want to play safe until this has been tested in the wild.

We have no indication of issues yet, other than those of using macros, any we do find we would hope to fix, much like any other clang-format bug.

I have run this on a number of significant code bases including turning large parts of clang itself into east cost, (not helped by LLVM lack of global clang-formatted status!)

The macro case is already mitigated but if people are using macros in this horrendous way AND their macros are lower case it would fail, but I don't feel the need to provide an example! I simply couldn't bring myself to write such horrible code! ;-)

clang/docs/ClangFormatStyleOptions.rst

 
 
 
 **QualifierAlignment** (``QualifierAlignmentStyle``) :versionbadge:`clang-format 14`
   Different ways to arrange const/volatile qualifiers.
 
   .. warning:: 
 
-   ``QualifierAlignment`` COULD lead to incorrect code generation.
+   Setting ``QualifierAlignment``  to something other than `Leave`, COULD
+   lead to incorrect code generation due to a lack of semantic information
+   especially in the presense of macros, care should be take to review code
+   changes made by this option.
 
   Possible values:
 
   * ``QAS_Leave`` (in configuration: ``Leave``)
     Don't change specifiers/qualifier to either Left or Right alignment
     (default)
 
     .. code-block:: c++

clang/include/clang/Format/Format.h

enum QualifierAlignmentStyle {
     ///    int const a;
     ///    int const *a;
     /// \endcode
     QAS_Custom
   };
 
   /// Different ways to arrange const/volatile qualifiers.
   /// \warning
-  ///  ``QualifierAlignment`` COULD lead to incorrect code generation.
+  ///  Setting ``QualifierAlignment``  to something other than `Leave`, COULD
+  ///  lead to incorrect code generation due to a lack of semantic information
+  ///  especially in the presense of macros, care should be take to review code
+  ///  changes made by this option.
   /// \endwarning
   /// \version 14
   QualifierAlignmentStyle QualifierAlignment;
 
   /// The Order in which the qualifiers appear.
   /// Order is a an array can contain any of the following
   ///
   ///   * const