[clang-format] Fix documentation for AllowAllParametersOfDeclarationOnNextLine

[LuMa]

Summary

Current description of flag AllowAllParametersOfDeclarationOnNextLine in Clang-Format Style Options guide suggests that it is possible to format function declaration, which fits in a single line (what is not supported in current clang-format version). Also example is not reproducible and makes no sense.
I have added valid example and have stressed that flag applies only if declaration doesn't fit in a single line.

[djasper]

Note that these changes need to be made to the corresponding comments in include/clang/Format/Format.h and then this file is auto-generated with docs/tools/dump_format_style.py.

docs/ClangFormatStyleOptions.rst

276

Much better phrasing, thank you.

280

I think this sentence does not add value.

281

I think we should keep the example as short as it was previously (it is reproducible with a very short column limit), but you are right that the example was broken. So I suggest making this:

void myFunction(
    int a, int b, int c);

vs.

void myFunction(
    int a,
    int b,
    int c);

[LuMa]

I moved changes to correct file.
When it comes to example, it doesn't seem to work with short function.

Example:

.clang-format:

ColumnLimit: 35
UseTab:          Never
BinPackParameters: false
AllowAllParametersOfDeclarationOnNextLine: true

For input:

void myFunction(int a, int b, int c);

output is:

void myFunction(int a,
                int b,
                int c);

although it should be:

void myFunction(
    int a, int b, int c);

I don't know if it's bug or expected behavior. Maybe it's result of other flags or penalties. But i think an example should work for default values, so i suggest using the longer one.

[djasper]

Also run dump_format_style.py and keep the changed .rst file in this change.

Otherwise looks good.

[LuMa]

I cannot commit the patch myself.

[djasper]

Submitted as r312721. Thank you.

[LuMa]

Thank you.

docs/ClangFormatStyleOptions.rst

**AlignTrailingComments** (``bool``)
 
   .. code-block:: c++
 
     true:                                   false:
     int a;     // My comment a      vs.     int a; // My comment a
     int b = 2; // comment  b                int b = 2; // comment about b
 
 **AllowAllParametersOfDeclarationOnNextLine** (``bool``)
-  Allow putting all parameters of a function declaration onto
+  If the function declaration doesn't fit on a line,
+  allow putting all parameters of a function declaration onto
   the next line even if ``BinPackParameters`` is ``false``.
 
   .. code-block:: c++
 
-    true:                                   false:
-    myFunction(foo,                 vs.     myFunction(foo, bar, plop);
-               bar,
-               plop);
+    true:
+    void myFunction(
+        int a, int b, int c, int d, int e);
+
+    false:
+    void myFunction(int a,
+                    int b,
+                    int c,
+                    int d,
+                    int e);
 
 **AllowShortBlocksOnASingleLine** (``bool``)
   Allows contracting simple braced statements to a single line.
 
   E.g., this allows ``if (a) { return; }`` to be put on a single line.
 
 **AllowShortCaseLabelsOnASingleLine** (``bool``)
   If ``true``, short case labels will be contracted to a single line.

include/clang/Format/Format.h

struct FormatStyle {
   /// \brief If ``true``, aligns trailing comments.
   /// \code
   ///   true:                                   false:
   ///   int a;     // My comment a      vs.     int a; // My comment a
   ///   int b = 2; // comment  b                int b = 2; // comment about b
   /// \endcode
   bool AlignTrailingComments;
 
-  /// \brief Allow putting all parameters of a function declaration onto
+  /// \brief If the function declaration doesn't fit on a line,
+  /// allow putting all parameters of a function declaration onto
   /// the next line even if ``BinPackParameters`` is ``false``.
   /// \code
-  ///   true:                                   false:
-  ///   myFunction(foo,                 vs.     myFunction(foo, bar, plop);
-  ///              bar,
-  ///              plop);
+  ///   true:
+  ///   void myFunction(
+  ///       int a, int b, int c, int d, int e);
+  ///   
+  ///   false:
+  ///   void myFunction(int a,
+  ///                   int b,
+  ///                   int c,
+  ///                   int d,
+  ///                   int e);
   /// \endcode
   bool AllowAllParametersOfDeclarationOnNextLine;
 
   /// \brief Allows contracting simple braced statements to a single line.
   ///
   /// E.g., this allows ``if (a) { return; }`` to be put on a single line.
   bool AllowShortBlocksOnASingleLine;