[clang-format][NFC] Improve documentation on ReflowComments

[HazardyKnusperkeks]

Summary

Fixes https://github.com/llvm/llvm-project/issues/58403

[owenpan]

clang/include/clang/Format/Format.h

3073–3076

Let's leave it as is because the new lines don't always get a leading *:

$ cat foo.cpp
/* The LLVM Project is a collection of modular and reusable compiler and toolchain
   technologies. */
$ clang-format -style='{ReflowComments: true}' foo.cpp
/* The LLVM Project is a collection of modular and reusable compiler and
   toolchain technologies. */

3863

We need an empty line after /// \endcode.

[owenpan]

clang/include/clang/Format/Format.h

3863

We need an empty line after /// \endcode.

We need an empty /// line.

[HazardyKnusperkeks]

clang/include/clang/Format/Format.h

3073–3076

That was from a short glimpse on the code.
Adapted the text.

[rymiel]

clang/include/clang/Format/Format.h

3073–3076

Let's leave it as is because the new lines don't always get a leading *:

I suppose this also ties into https://github.com/llvm/llvm-project/issues/58710

clang/docs/ClangFormatStyleOptions.rst

* ``RAS_Middle`` (in configuration: ``Middle``)
 
     .. code-block:: c++
 
       int & a;
 
 
 
 **ReflowComments** (``Boolean``) :versionbadge:`clang-format 3.8`
-  If ``true``, clang-format will attempt to re-flow comments.
+  If ``true``, clang-format will attempt to re-flow comments. That is it
+  will touch a comment and *reflow* long comments into new lines, trying to
+  obey the ``ColumnLimit``.
 
   .. code-block:: c++
 
      false:
      // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
      /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
 
      true:
.. code-block:: c++
     //  return true;                          //   return true;
     //}                                       // }
 
     Maximum: 0
     /// List:                                 ///List:
     ///  - Foo                                /// - Foo
     ///    - Bar                              ///   - Bar
 
+  This option has only effect if ``ReflowComments`` is set to ``true``.
+
   Nested configuration flags:
 
-  Control of spaces within a single line comment
+  Control of spaces within a single line comment.
 
   * ``unsigned Minimum`` The minimum number of spaces at the start of the comment.
 
   * ``unsigned Maximum`` The maximum number of spaces at the start of the comment.
 
 
 **SpacesInParentheses** (``Boolean``) :versionbadge:`clang-format 3.7`
   If ``true``, spaces will be inserted after ``(`` and before ``)``.

clang/include/clang/Format/Format.h

   };
 
   /// \brief Reference alignment style (overrides ``PointerAlignment`` for
   /// references).
   /// \version 13
   ReferenceAlignmentStyle ReferenceAlignment;
 
   // clang-format off
-  /// If ``true``, clang-format will attempt to re-flow comments.
+  /// If ``true``, clang-format will attempt to re-flow comments. That is it
+  /// will touch a comment and *reflow* long comments into new lines, trying to
+  /// obey the ``ColumnLimit``.
   /// \code
   ///    false:
   ///    // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information
   ///    /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of information */
   ///
   ///    true:
   ///    // veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of
   ///    // information
   ///    /* second veryVeryVeryVeryVeryVeryVeryVeryVeryVeryVeryLongComment with plenty of

   /// If ``true``, spaces may be inserted into C style casts.
   /// \code
   ///    true:                                  false:
   ///    x = ( int32 )y                 vs.     x = (int32)y
   /// \endcode
   /// \version 3.7
   bool SpacesInCStyleCastParentheses;
 
-  /// Control of spaces within a single line comment
+  /// Control of spaces within a single line comment.
   struct SpacesInLineComment {
     /// The minimum number of spaces at the start of the comment.
     unsigned Minimum;
     /// The maximum number of spaces at the start of the comment.
     unsigned Maximum;
   };
 
   /// How many spaces are allowed at the start of a line comment. To disable the

   ///   //  return true;                          //   return true;
   ///   //}                                       // }
   ///
   ///   Maximum: 0
   ///   /// List:                                 ///List:
   ///   ///  - Foo                                /// - Foo
   ///   ///    - Bar                              ///   - Bar
   /// \endcode
+  ///
+  /// This option has only effect if ``ReflowComments`` is set to ``true``.
   /// \version 13
   SpacesInLineComment SpacesInLineCommentPrefix;
 
   /// If ``true``, spaces will be inserted after ``(`` and before ``)``.
   /// \code
   ///    true:                                  false:
   ///    t f( Deleted & ) & = delete;   vs.     t f(Deleted &) & = delete;
   /// \endcode