[Clang-tidy] Fix style in some checks documentation

[alexfh]

docs/clang-tidy/checks/cppcoreguidelines-pro-bounds-constant-array-index.rst

11 ↗

(On Diff #68739)

I don't see the rest of the file (upload full diffs, btw), but we need to add .. option:: GslHeader, if it's not there yet. And I think, the general rule should be to add option description in every check that uses the option, since different checks can use the same global option in a subtly different ways.

I hope, Sphinx supports this use case.

[alexfh]

Please rebase your patch, I've made some changes to some of these files.

docs/clang-tidy/checks/misc-misplaced-widening-cast.rst

39 ↗

(On Diff #68739)

The .. option:: CheckImplicitCasts block should be added in this document to prevent Sphinx warnings. In order to verify this, you should install Sphinx 1.4.5 (on linux this can be done using pip install -u Sphinx, not sure about Windows).

57 ↗

(On Diff #68739)

No space after the closing parenthesis is needed. Same above.

[Eugene.Zelenko]

Address review comments.

[alexfh]

LG with a few nits.

docs/clang-tidy/checks/cppcoreguidelines-pro-bounds-constant-array-index.rst

9 ↗

(On Diff #68908)

Can we make this a link?

19 ↗

(On Diff #68908)

nit: "the this" - one of these should go

docs/clang-tidy/checks/misc-misplaced-widening-cast.rst

19 ↗

(On Diff #68908)

x * 1000 should also be enclosed in double quotes, imo.

65 ↗

(On Diff #68908)

I'd say "If non-zero, enables detection of implicit casts. Default is non-zero."

[Eugene.Zelenko]

Address review comments.

[Eugene.Zelenko]

docs/clang-tidy/checks/cppcoreguidelines-pro-bounds-constant-array-index.rst

9 ↗

(On Diff #68921)

Unfortunately not. Historically Clang warnings options documentation is very poor in comparison with GCC's.

Probably some descriptions could be extracted from release notes, but I'm not sure that clang-diagnostic-array-bounds is described there.

[alexfh]

docs/clang-tidy/checks/cppcoreguidelines-pro-bounds-constant-array-index.rst

9 ↗

(On Diff #68921)

Ah, I completely missed the fact it's a clang diagnostic. The wording is off here. Should be "see the -Warray-bounds clang diagnostic" instead. The fact that clang diagnostics map to clang-diagnostic-... is described in the main doc (http://clang.llvm.org/extra/clang-tidy/).

[Eugene.Zelenko]

Address review comment.

[alexfh]

In D23728#522710, @Eugene.Zelenko wrote:

Address review comment.

Thanks! Still LG.

clang-tools-extra/trunk/docs/clang-tidy/checks/cppcoreguidelines-pro-bounds-constant-array-index.rst

 .. title:: clang-tidy - cppcoreguidelines-pro-bounds-constant-array-index
 
 cppcoreguidelines-pro-bounds-constant-array-index
 =================================================
 
 This check flags all array subscript expressions on static arrays and
 ``std::arrays`` that either do not have a constant integer expression index or
 are out of bounds (for ``std::array``). For out-of-bounds checking of static
-arrays, see the clang-diagnostic-array-bounds check.
-
-The check can generate fixes after the option `GslHeader` has been set
-to the name of the include file that contains ``gsl::at()``, e.g. `"gsl/gsl.h"`.
+arrays, see the `-Warray-bounds` Clang diagnostic.
 
 This rule is part of the "Bounds safety" profile of the C++ Core Guidelines, see
 https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-bounds-arrayindex.
+
+Options
+-------
+
+.. option:: GslHeader
+
+   The check can generate fixes after this option has been set to the name of
+   the include file that contains ``gsl::at()``, e.g. `"gsl/gsl.h"`.

clang-tools-extra/trunk/docs/clang-tidy/checks/google-global-names-in-headers.rst

 .. title:: clang-tidy - google-global-names-in-headers
 
 google-global-names-in-headers
 ==============================
 
-Flag global namespace pollution in header files.
-Right now it only triggers on ``using`` declarations and directives.
-
-The check supports these options:
-  - `HeaderFileExtensions`: a comma-separated list of filename extensions
-    of header files (the filename extensions should not contain "." prefix).
-    "h" by default.
-    For extension-less header files, using an empty string or leaving an
-    empty string between "," if there are other filename extensions.
+Flag global namespace pollution in header files. Right now it only triggers on
+``using`` declarations and directives.
 
 The relevant style guide section is
 https://google.github.io/styleguide/cppguide.html#Namespaces.
+
+Options
+-------
+
+.. option:: HeaderFileExtensions
+
+   A comma-separated list of filename extensions of header files (the filename
+   extensions should not contain "." prefix). "h" by default. For extension-less
+   header files, using an empty string or leaving an empty string between ","
+   if there are other filename extensions.

clang-tools-extra/trunk/docs/clang-tidy/checks/misc-argument-comment.rst

 .. title:: clang-tidy - misc-argument-comment
 
 misc-argument-comment
 =====================
 
-
 Checks that argument comments match parameter names.
 
 The check understands argument comments in the form ``/*parameter_name=*/``
 that are placed right before the argument.
 
-.. code:: c++
+.. code-block:: c++
 
   void f(bool foo);
 
   ...
+
   f(/*bar=*/true);
   // warning: argument name 'bar' in comment does not match parameter name 'foo'
 
 The check tries to detect typos and suggest automated fixes for them.
 
-Supported options:
-  - `StrictMode` (local or global): when non-zero, the check will ignore leading
-    and trailing underscores and case when comparing parameter names.
+Options
+-------
+
+.. option:: StrictMode
+
+   When non-zero, the check will ignore leading and trailing underscores and
+   case when comparing parameter names.

clang-tools-extra/trunk/docs/clang-tidy/checks/misc-misplaced-widening-cast.rst

 .. title:: clang-tidy - misc-misplaced-widening-cast
 
 misc-misplaced-widening-cast
 ============================
 
 This check will warn when there is a cast of a calculation result to a bigger
 type. If the intention of the cast is to avoid loss of precision then the cast
 is misplaced, and there can be loss of precision. Otherwise the cast is
 ineffective.
 
-Example code::
+Example code:
+
+.. code-block:: c++
 
     long f(int x) {
-        return (long)(x*1000);
+        return (long)(x * 1000);
     }
 
-The result x*1000 is first calculated using int precision. If the result
-exceeds int precision there is loss of precision. Then the result is casted to
-long.
+The result ``x * 1000`` is first calculated using ``int`` precision. If the
+result exceeds ``int`` precision there is loss of precision. Then the result is
+casted to ``long``.
 
 If there is no loss of precision then the cast can be removed or you can
-explicitly cast to int instead.
+explicitly cast to ``int`` instead.
 
 If you want to avoid loss of precision then put the cast in a proper location,
-for instance::
+for instance:
+
+.. code-block:: c++
 
     long f(int x) {
         return (long)x * 1000;
     }
 
 Implicit casts
 --------------
 
 Forgetting to place the cast at all is at least as dangerous and at least as
-common as misplacing it. If option ``CheckImplicitCasts`` is enabled (default)
-the checker also detects these cases, for instance::
+common as misplacing it. If :option:`CheckImplicitCasts` is enabled the check
+also detects these cases, for instance:
+
+.. code-block:: c++
 
     long f(int x) {
         return x * 1000;
     }
 
 Floating point
 --------------
 
 Currently warnings are only written for integer conversion. No warning is
-written for this code::
+written for this code:
+
+.. code-block:: c++
 
     double f(float x) {
         return (double)(x * 10.0f);
     }
+
+Options
+-------
+
+.. option:: CheckImplicitCasts
+
+   If non-zero, enables detection of implicit casts. Default is non-zero.

clang-tools-extra/trunk/docs/clang-tidy/checks/misc-suspicious-missing-comma.rst

 .. title:: clang-tidy - misc-suspicious-missing-comma
 
 misc-suspicious-missing-comma
 =============================
 
 String literals placed side-by-side are concatenated at translation phase 6
 (after the preprocessor). This feature is used to represent long string
 literal on multiple lines.
 
 For instance, the following declarations are equivalent:
 
-.. code:: c++
+.. code-block:: c++
 
   const char* A[] = "This is a test";
   const char* B[] = "This" " is a "    "test";
 
-
 A common mistake done by programmers is to forget a comma between two string
 literals in an array initializer list.
 
-.. code:: c++
+.. code-block:: c++
 
   const char* Test[] = {
     "line 1",
     "line 2"     // Missing comma!
     "line 3",
     "line 4",
     "line 5"
   };
 
-
 The array contains the string "line 2line3" at offset 1 (i.e. Test[1]). Clang
 won't generate warnings at compile time.
 
-This checker may warn incorrectly on cases like:
+This check may warn incorrectly on cases like:
 
-.. code:: c++
+.. code-block:: c++
 
   const char* SupportedFormat[] = {
     "Error %s",
     "Code " PRIu64,   // May warn here.
     "Warning %s",
   };
-

clang-tools-extra/trunk/docs/clang-tidy/checks/modernize-use-auto.rst

.. code-block:: c++
   TypeName *my_first_pointer = new TypeName, *my_second_pointer = new TypeName;
 
   // becomes
 
   auto *my_first_pointer = new TypeName, *my_second_pointer = new TypeName;
 
 Known Limitations
 -----------------
+
 * If the initializer is an explicit conversion constructor, the check will not
   replace the type specifier even though it would be safe to do so.
 
 * User-defined iterators are not handled at this time.
 
-RemoveStars option
-------------------
-If the option is set to non-zero (default is `0`), the check will remove stars
-from the non-typedef pointer types when replacing type names with ``auto``.
-Otherwise, the check will leave stars. For example:
+Options
+-------
+
+.. option:: RemoveStars
+
+   If the option is set to non-zero (default is `0`), the check will remove
+   stars from the non-typedef pointer types when replacing type names with
+   ``auto``. Otherwise, the check will leave stars. For example:
 
 .. code-block:: c++
 
   TypeName *my_first_pointer = new TypeName, *my_second_pointer = new TypeName;
 
   // RemoveStars = 0
 
   auto *my_first_pointer = new TypeName, *my_second_pointer = new TypeName;
 
   // RemoveStars = 1
 
   auto my_first_pointer = new TypeName, my_second_pointer = new TypeName;

clang-tools-extra/trunk/docs/clang-tidy/checks/readability-braces-around-statements.rst

 .. title:: clang-tidy - readability-braces-around-statements
 
 readability-braces-around-statements
 ====================================
 
 `google-readability-braces-around-statements` redirects here as an alias for
 this check.
 
 Checks that bodies of ``if`` statements and loops (``for``, ``do while``, and
 ``while``) are inside braces.
 
 Before:
 
-.. code:: c++
+.. code-block:: c++
 
   if (condition)
     statement;
 
 After:
 
-.. code:: c++
+.. code-block:: c++
 
   if (condition) {
     statement;
   }
 
 Options
 -------