[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

docs/ClangFormatStyleOptions.rst

 
     .. code-block:: c++
 
-      try {
-        foo();
+      try
+      {
+          foo();
       }
-      catch () {
+      catch ()
+      {
       }
-      void foo() { bar(); }
-      class foo {
+      void foo()
+      {
+          bar();
+      }
+      class foo
+      {
       };
-      if (foo()) {
+      if (foo())
+      {
       }
-      else {
+      else
+      {
       }
-      enum X : int { A, B };
+      enum X : int
+      {
+          A,
+          B
+      };
 
   * ``BS_GNU`` (in configuration: ``GNU``)
     Always break before braces and add an extra level of indentation to

          ? firstValue
          : SecondValueVeryVeryVeryVeryLong;
 
-     true:
+     false:
      veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongDescription ?
          firstValue :
          SecondValueVeryVeryVeryVeryLong;

 
 **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.

 
   When ``false``, use the same indentation level as for the switch statement.
   Switch statement body is always indented one level more than case labels.
+  
+  .. code-block:: c++
+
+    true:
+    switch (type) {
+        case FirstCase:
+            FirstFunction();
+            break;
+
+        case SecondCase: {
+            SecondFunction();
+        }
+        break;
+    }
+
+    false:
+    switch (type) {
+    case FirstCase:
+        FirstFunction();
+        break;
+
+    case SecondCase: {
+        SecondFunction();
+    }
+    break;
+    }
 
 **IndentWidth** (``unsigned``)
   The number of columns to use for indentation.

 
 **KeepEmptyLinesAtTheStartOfBlocks** (``bool``)
   If true, empty lines at the start of blocks are kept.
+  
+  .. code-block:: c++
+
+    true:
+    void foo() {
+
+        bar();
+    }
+
+    false:
+    void foo() {
+        bar();
+    }
 
 **Language** (``LanguageKind``)
   Language, this format style is targeted at.