[clang-format] update documentation

[mrexodia]

Summary

• Added example code for BreakStringLiterals;

[djasper]

This file is auto-generated from include/clang/format/Format.h. Changes need to be made there and then this files needs to be regenerated with docs/tools/dump_format_style.py. Sorry, we probably need to make that more obvious.

[mrexodia]

In D31574#716152, @djasper wrote:

This file is auto-generated from include/clang/format/Format.h. Changes need to be made there and then this files needs to be regenerated with docs/tools/dump_format_style.py. Sorry, we probably need to make that more obvious.

Alright, I moved my changes to the source code.

[MyDeveloperDay]

@mrexodia, Thank you for this patch, I'm sorry you've had no response, I'm trying to go through some of the old reviews.

This revision needs rebasing, at least some of the changes have been already made, and I'm not sure about the Mozilla Bracing Style is quite right, but your other examples will help to improve the documentation.

include/clang/Format/Format.h

447 ↗

(On Diff #93818)

Are you sure this is correct? I tried a small example and didn't get this

[mrexodia]

If I'm not mistaken the documentation I updated was not for BS_Mozilla, but for BS_Stroustrup. It's been a very long time though so I absolutely don't remember unfortunately.

[MyDeveloperDay]

I tried that too

---
Language: Cpp
BreakBeforeBraces: Stroustrup
...

But I don't seem to get the style for that either, maybe I did something wrong?

try {
  foo();
}
catch () {
}
void foo() { bar(); }
class foo {
};
if (foo()) {
}
else {
}

[MyDeveloperDay]

Looking here https://en.wikipedia.org/wiki/Indentation_style#Variant:_Stroustrup I think the original document wasn't quite correct its the "cuddled" catch and else that the Stroustrup style doesn't have

i.e.

}
else {

rather than

} else {

[mrexodia]

Okay I remember what happened now. In the past Allman and Stroustroup had the same documentation (Allman being incorrect), so I updated the documentation for Allman, but by accident I updated the documentation for Stroustroup instead. Anyway I went over the changes and will upload a new diff with the ones that are still relevant today.

[MyDeveloperDay]

LGTM

[MyDeveloperDay]

When I land this change, I'll include the ClangFormatStyleOptions.rst to match (plus some minor NFC) in Format.h that are preventing dump_format_style.py from being rerun

in a later commit I'll try and bring the Format.h and ClangFormaatStyleOptions.rst back into line

clang/docs/ClangFormatStyleOptions.rst

.. code-block:: c++
            Base2
        {};
 
 
 
 **BreakStringLiterals** (``bool``)
   Allow breaking string literals when formatting.
 
+  .. code-block:: c++
+
+     true:
+     const char* x = "veryVeryVeryVeryVeryVe"
+                     "ryVeryVeryVeryVeryVery"
+                     "VeryLongString";
+
+     false:
+     const char* x =
+       "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString";
+
 **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``)

clang/include/clang/Format/Format.h

enum BraceBreakingStyle {
     BS_WebKit,
     /// Configure each individual brace in `BraceWrapping`.
     BS_Custom
   };
 
   /// The brace breaking style to use.
   BraceBreakingStyle BreakBeforeBraces;
 
-  // Different ways to wrap braces after control statements.
+  /// Different ways to wrap braces after control statements.
   enum BraceWrappingAfterControlStatementStyle {
     /// Never wrap braces after a control statement.
     /// \code
     ///   if (foo()) {
     ///   } else {
     ///   }
     ///   for (int i = 0; i < 10; ++i) {
     ///   }

   ///    true:                                  false:
   ///    @Partial                       vs.     @Partial @Mock DataLoad loader;
   ///    @Mock
   ///    DataLoad loader;
   /// \endcode
   bool BreakAfterJavaFieldAnnotations;
 
   /// Allow breaking string literals when formatting.
+  /// \code
+  ///    true:
+  ///    const char* x = "veryVeryVeryVeryVeryVe"
+  ///                    "ryVeryVeryVeryVeryVery"
+  ///                    "VeryLongString";
+  ///
+  ///    false:
+  ///    const char* x =
+  ///      "veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongString";
+  /// \endcode
   bool BreakStringLiterals;
 
   /// 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.
   unsigned ColumnLimit;
enum LanguageStandard {
     LS_Cpp14,
     /// c++17: Parse and format as C++17.
     LS_Cpp17,
     /// c++20: Parse and format as C++20.
     LS_Cpp20,
     /// Latest: Parse and format using the latest supported language version.
     /// 'Cpp11' is an alias for LS_Latest for historical reasons.
     LS_Latest,
-
     /// Auto: Automatic detection based on the input.
     /// Parse using the latest language version. Format based on detected input.
     LS_Auto,
   };
 
   /// Format compatible with this standard, e.g. use ``A<A<int> >``
   /// instead of ``A<A<int>>`` for ``LS_Cpp03``.
   LanguageStandard Standard;