[clang] 6df7ef0 - [clang-format] [NFC] update the documentation in Format.h to allow dump_format_style.py to get a little closer to being correct.

[via cfe-commits]

Author: paulhoad
Date: 2019-10-25T14:46:19+01:00
New Revision: 6df7ef0d8baac34259e2c93043d843f27812c534

URL: https://github.com/llvm/llvm-project/commit/6df7ef0d8baac34259e2c93043d843f27812c534
DIFF: https://github.com/llvm/llvm-project/commit/6df7ef0d8baac34259e2c93043d843f27812c534.diff

LOG: [clang-format] [NFC] update the documentation in Format.h to allow dump_format_style.py to get a little closer to being correct.

Summary:
Running dump_format_style.py on the tip of the trunk causes ClangFormatStyleOptions.rst to have changes, which I think ideally it shouldn't.

Some recent commits have meant Format.h and ClangFormatStyleOptions.rst have become out of sync such that dump_format_style.py either couldn't be run or generated incorrect .rst files.

It's also important to remember to edit the IncludeStyles from Tooling.

Make a couple of changes {D6833} {D64695} which came from recent clang-format commits that missed this step. There are still a couple of other changes  from commit {D67541} {D68296} which also need to be looked at, but I'd like to park these first two changes first.

The authors of these original commits I've included in the reviewers, I'm happy to work on the changes, just really need to know which is the ground truth of the changes you want to keep (whats in the Format.h) or what is in the ClangFormatStyleOptions.rst

Reviewers: klimek, mitchell-stellar, owenpan, jvoung, Manikishan, sammccall

Reviewed By: mitchell-stellar

Subscribers: cfe-commits

Tags: #clang-format, #clang

Differential Revision: https://reviews.llvm.org/D69404

Added: 
    

Modified: 
    clang/include/clang/Format/Format.h
    clang/include/clang/Tooling/Inclusions/IncludeStyle.h

Removed: 
    


################################################################################
diff  --git a/clang/include/clang/Format/Format.h b/clang/include/clang/Format/Format.h
index 1095821eb664..b38d1f7d9402 100644
--- a/clang/include/clang/Format/Format.h
+++ b/clang/include/clang/Format/Format.h
@@ -706,21 +706,19 @@ struct FormatStyle {
     ///   };
     /// \endcode
     BS_Allman,
-    /// Always break before braces and add an extra level of indentation to
-    /// braces of control statements, not to those of class, function
-    /// or other definitions.
+    /// Like ``Allman`` but always indent braces and line up code with braces.
     /// \code
-    ///   try
+    ///    try
     ///     {
-    ///       foo();
+    ///     foo();
     ///     }
     ///   catch ()
     ///     {
     ///     }
     ///   void foo() { bar(); }
     ///   class foo
-    ///   {
-    ///   };
+    ///     {
+    ///     };
     ///   if (foo())
     ///     {
     ///     }
@@ -728,25 +726,27 @@ struct FormatStyle {
     ///     {
     ///     }
     ///   enum X : int
-    ///   {
+    ///     {
     ///     A,
     ///     B
-    ///   };
+    ///     };
     /// \endcode
     BS_Whitesmiths,
-    /// Like ``Allman`` but always indent braces and line up code with braces.
+    /// Always break before braces and add an extra level of indentation to
+    /// braces of control statements, not to those of class, function
+    /// or other definitions.
     /// \code
-    ///    try
+    ///   try
     ///     {
-    ///     foo();
+    ///       foo();
     ///     }
     ///   catch ()
     ///     {
     ///     }
     ///   void foo() { bar(); }
     ///   class foo
-    ///     {
-    ///     };
+    ///   {
+    ///   };
     ///   if (foo())
     ///     {
     ///     }
@@ -754,10 +754,10 @@ struct FormatStyle {
     ///     {
     ///     }
     ///   enum X : int
-    ///     {
+    ///   {
     ///     A,
     ///     B
-    ///     };
+    ///   };
     /// \endcode
     BS_GNU,
     /// Like ``Attach``, but break before functions.

diff  --git a/clang/include/clang/Tooling/Inclusions/IncludeStyle.h b/clang/include/clang/Tooling/Inclusions/IncludeStyle.h
index 266763a5b1bd..9cade29a8545 100644
--- a/clang/include/clang/Tooling/Inclusions/IncludeStyle.h
+++ b/clang/include/clang/Tooling/Inclusions/IncludeStyle.h
@@ -84,18 +84,27 @@ struct IncludeStyle {
   /// (https://llvm.org/docs/CodingStandards.html#include-style). However, you
   /// can also assign negative priorities if you have certain headers that
   /// always need to be first.
+  /// 
+  /// There is a third and optional field ``SortPriority`` which can used while
+  /// ``IncludeBloks = IBS_Regroup`` to define the priority in which ``#includes``
+  /// should be ordered, and value of ``Priority`` defines the order of
+  /// ``#include blocks`` and also enables to group ``#includes`` of 
diff erent
+  /// priority for order.``SortPriority`` is set to the value of ``Priority``
+  /// as default if it is not assigned.
   ///
   /// To configure this in the .clang-format file, use:
   /// \code{.yaml}
   ///   IncludeCategories:
   ///     - Regex:           '^"(llvm|llvm-c|clang|clang-c)/'
   ///       Priority:        2
+  ///       SortPriority:    2
   ///     - Regex:           '^(<|"(gtest|gmock|isl|json)/)'
   ///       Priority:        3
   ///     - Regex:           '<[[:alnum:].]+>'
   ///       Priority:        4
   ///     - Regex:           '.*'
   ///       Priority:        1
+  ///       SortPriority:    0
   /// \endcode
   std::vector<IncludeCategory> IncludeCategories;