[clang-format] NFC allow Format.h to be clang-formatted but still maintain the same doc layout in ClangFormatStyleOptions.rst

[MyDeveloperDay]

Summary

Format.h is used to generate ClangFormatStyleOptions.rst, the layout of the comments is critical to the rst file. Accidentally clang-formatting Format.h can lead to the .rst changing.

This revision simply add // clang-format off/on statement around the areas who formatting needs to be maintained, mainly around the options that are related to what happens when the line breaks due to ColumnLimit (which is what is happening to the comment)

This allows Format.h to be clang-formatted without causing a change in the documentation when dump_format_style.py is rerun, which is also part of the revision.

[mitchell-stellar]

clang/include/clang/Format/Format.h

1309

Can this documentation be formatted in a way that avoids clang-format reformatting it? It doesn't look like it depends on long lines like the other bits in this change.

[MyDeveloperDay]

clang/include/clang/Format/Format.h

1309

It's this line..

it turns:

When ``false``, use the same indentation level as for the switch statement.
Switch statement body is always indented one level more than case labels.

into:

When ``false``, use the same indentation level as for the switch
statement. Switch statement body is always indented one level more than
case labels.

My assumption was that the author wanted the "Switch statement.." to be a new paragraph, but if we don't mind then we could lose this one

[mitchell-stellar]

clang/include/clang/Format/Format.h

1309

The HTML is no different. If the author wanted a separate paragraph, I suspect that person would have used two line breaks. I would reformat this one and remove the clang-format switches.

[MyDeveloperDay]

clang/include/clang/Format/Format.h

1309

Sounds good, you are quite correct, the text is all on the same line anyway

[MyDeveloperDay]

remove one set of // clang-format on/off that has no visual impact to the html

NOTE: it does change the baseline .rst which is why its been added into the review.

[mitchell-stellar]

clang/docs/ClangFormatStyleOptions.rst

1594

This generated rst is not correct. See below.

clang/include/clang/Format/Format.h

1316

\code needs to be on its own line. Otherwise you get the incorrectly generated .rst I mentioned earlier.

[mitchell-stellar]

LGTM

clang/docs/ClangFormatStyleOptions.rst

**IncludeIsMainRegex** (``std::string``)
   - "$" 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.
 
 **IndentCaseLabels** (``bool``)
   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.
+  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++
 
      false:                                 true:
      switch (fool) {                vs.     switch (fool) {
      case 1:                                  case 1:
        bar();                                   bar();
        break;                                   break;
      default:                                 default:
        plop();                                  plop();
      }                                      }
 
 **IndentGotoLabels** (``bool``)

clang/include/clang/Format/Format.h

   /// wrapped:
   /// \code
   ///   namespace Foo { namespace Bar {
   ///   namespace Extra {
   ///   }}}
   /// \endcode
   bool CompactNamespaces;
 
+  // clang-format off
   /// If the constructor initializers don't fit on a line, put each
   /// initializer on its own line.
   /// \code
   ///   true:
   ///   SomeClass::Constructor()
   ///       : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) {
   ///     return 0;
   ///   }
   ///
   ///   false:
   ///   SomeClass::Constructor()
   ///       : aaaaaaaa(aaaaaaaa), aaaaaaaa(aaaaaaaa),
   ///         aaaaaaaa(aaaaaaaaaaaaaaaaaaaaaaaaa) {
   ///     return 0;
   ///   }
   /// \endcode
   bool ConstructorInitializerAllOnOneLineOrOnePerLine;
+  // clang-format on
 
   /// The number of characters to use for indentation of constructor
   /// initializer lists as well as inheritance lists.
   unsigned ConstructorInitializerIndentWidth;
 
   /// Indent width for line continuations.
   /// \code
   ///    ContinuationIndentWidth: 2

   ///   }
   /// \endcode
   ///
   /// For example: TESTSUITE
   std::vector<std::string> NamespaceMacros;
 
   tooling::IncludeStyle IncludeStyle;
 
   /// 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.
+  /// 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
   ///    false:                                 true:
   ///    switch (fool) {                vs.     switch (fool) {
   ///    case 1:                                  case 1:
   ///      bar();                                   bar();
   ///      break;                                   break;
   ///    default:                                 default:
   ///      plop();                                  plop();
   ///    }                                      }
   /// \endcode
   bool IndentCaseLabels;
enum JavaScriptQuoteStyle {
     ///    string2 = "bar";
     /// \endcode
     JSQS_Double
   };
 
   /// The JavaScriptQuoteStyle to use for JavaScript strings.
   JavaScriptQuoteStyle JavaScriptQuotes;
 
+  // clang-format off
   /// Whether to wrap JavaScript import/export statements.
   /// \code{.js}
   ///    true:
   ///    import {
   ///        VeryLongImportsAreAnnoying,
   ///        VeryLongImportsAreAnnoying,
   ///        VeryLongImportsAreAnnoying,
   ///    } from 'some/module.js'
   ///
   ///    false:
   ///    import {VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying, VeryLongImportsAreAnnoying,} from "some/module.js"
   /// \endcode
   bool JavaScriptWrapImports;
+  // clang-format on
 
   /// If true, the empty line at the start of blocks is kept.
   /// \code
   ///    true:                                  false:
   ///    if (foo) {                     vs.     if (foo) {
   ///                                             bar();
   ///      bar();                               }
   ///    }

   ///         Delimiters:
   ///           - 'cc'
   ///           - 'cpp'
   ///         BasedOnStyle: llvm
   ///         CanonicalDelimiter: 'cc'
   /// \endcode
   std::vector<RawStringFormat> RawStringFormats;
 
+  // clang-format off
   /// If ``true``, clang-format will attempt to re-flow comments.
   /// \code
   ///    false:
   ///    // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
   ///    /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
   ///
   ///    true:
   ///    // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
   ///    // information
   ///    /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
   ///     * information */
   /// \endcode
   bool ReflowComments;
+  // clang-format on
 
   /// If ``true``, clang-format will sort ``#includes``.
   /// \code
   ///    false:                                 true:
   ///    #include "b.h"                 vs.     #include "a.h"
   ///    #include "a.h"                         #include "b.h"
   /// \endcode
   bool SortIncludes;
tooling::Replacements reformat(const FormatStyle &Style, StringRef Code,
                                StringRef FileName = "<stdin>",
                                FormattingAttemptStatus *Status = nullptr);
 
 /// Same as above, except if ``IncompleteFormat`` is non-null, its value
 /// will be set to true if any of the affected ranges were not formatted due to
 /// a non-recoverable syntax error.
 tooling::Replacements reformat(const FormatStyle &Style, StringRef Code,
                                ArrayRef<tooling::Range> Ranges,
-                               StringRef FileName,
-                               bool *IncompleteFormat);
+                               StringRef FileName, bool *IncompleteFormat);
 
 /// Clean up any erroneous/redundant code in the given \p Ranges in \p
 /// Code.
 ///
 /// Returns the ``Replacements`` that clean up all \p Ranges in \p Code.
 tooling::Replacements cleanup(const FormatStyle &Style, StringRef Code,
                               ArrayRef<tooling::Range> Ranges,
                               StringRef FileName = "<stdin>");

 }
 
 } // end namespace format
 } // end namespace clang
 
 namespace std {
 template <>
 struct is_error_code_enum<clang::format::ParseError> : std::true_type {};
-}
+} // namespace std
 
 #endif // LLVM_CLANG_FORMAT_FORMAT_H