[clang/docs] Fix various sphinx warnings/errors in docs.

[fhahn]

Summary

There are a few places with unexpected indents that trip over sphinx and
other syntax errors.

Also, the C++ syntax highlighting does not work for

class [[gsl::Owner(int)]] IntOwner {

Use a regular code:: block instead.

There are a few other warnings errors remaining, of the form
'Duplicate explicit target name: "cmdoption-clang--prefix"'. They seem
to be caused by the following

.. option:: -B<dir>, --prefix <arg>, --prefix=<arg>

I am no Restructured Text expert, but it seems like sphinx 1.8.5
tries to generate the same target for the --prefix <arg> and
--prefix=<arg>. This pops up in a lot of places and I am not sure how to
best resolve it

[rjmccall]

Is the option issue causing the documentation to be wrong in any way, or does it just produce a warning? If the latter, we could raise this issue with them.

[fhahn]

In D76534#1934943, @rjmccall wrote:

Is the option issue causing the documentation to be wrong in any way, or does it just produce a warning? If the latter, we could raise this issue with them.

I think it just produces a warning, it looks like sphinx still creates unique labels, e.g. https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang-flto for -flto and https://clang.llvm.org/docs/ClangCommandLineReference.html#cmdoption-clang1-flto for -flto=. But LLVM/Clang defaults to SPHINX_WARNINGS_AS_ERRORS=ON and there are quite a few instances of this warning.

[rjmccall]

Sure. I'm not asking you to fix this, I'm just asking your opinion about the right thing to do. Is the Sphinx warning reasonable, such that we should fix our (autogenerated, IIRC) input to avoid the "redundant" spellings, or should we ask Sphinx to handle it more gracefully in the future?

clang/docs/InternalsManual.rst

are created implicitly. The following spellings are accepted:
 
   ============  ================================================================
   Spelling      Description
   ============  ================================================================
   ``GNU``       Spelled with a GNU-style ``__attribute__((attr))`` syntax and
                 placement.
   ``CXX11``     Spelled with a C++-style ``[[attr]]`` syntax with an optional
                 vendor-specific namespace.
-  ``C2x``       Spelled with a C-style ``[[attr]]` syntax with an optional
+  ``C2x``       Spelled with a C-style ``[[attr]]`` syntax with an optional
                 vendor-specific namespace.
   ``Declspec``  Spelled with a Microsoft-style ``__declspec(attr)`` syntax.
   ``Keyword``   The attribute is spelled as a keyword, and required custom
                 parsing.
   ``GCC``       Specifies two spellings: the first is a GNU-style spelling, and
                 the second is a C++-style spelling with the ``gnu`` namespace.
                 Attributes should only specify this spelling for attributes
                 supported by GCC.

clang/docs/LanguageExtensions.rst

 the clang implementation are in :doc:`Block-ABI-Apple<Block-ABI-Apple>`.
 
 Query for this feature with ``__has_extension(blocks)``.
 
 ASM Goto with Output Constraints
 ================================
 
 In addition to the functionality provided by `GCC's extended
-assembly`<https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html>`_, clang
+assembly <https://gcc.gnu.org/onlinedocs/gcc/Extended-Asm.html>`_, clang
 supports output constraints with the `goto` form.
 
 The goto form of GCC's extended assembly allows the programmer to branch to a C
 label from within an inline assembly block. Clang extends this behavior by
 allowing the programmer to use output constraints:
 
 .. code-block:: c++
 

clang/docs/OpenMPSupport.rst

 | device extension             | OMP_TARGET_OFFLOAD environment variable                      | :good:`done`             | D50522                                                                |
 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 | device extension             | support full 'defaultmap' functionality                      | :good:`done`             | D69204                                                                |
 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 | device extension             | device specific functions                                    | :good:`done`             |                                                                       |
 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 | device extension             | clause: device_type                                          | :good:`done`             |                                                                       |
 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device extension             | clause: extended device                                      | :good:`done`             |                                                                    |
+| device extension             | clause: extended device                                      | :good:`done`             |                                                                       |
 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device extension             | clause: uses_allocators clause                               | :none:`claimed`          |                                                                    |
+| device extension             | clause: uses_allocators clause                               | :none:`claimed`          |                                                                       |
 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 | device extension             | clause: in_reduction                                         | :part:`worked on`        | r308768                                                               |
 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 | device extension             | omp_get_device_num()                                         | :part:`worked on`        | D54342                                                                |
 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 | device extension             | structure mapping of references                              | :none:`unclaimed`        |                                                                       |
 +------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
 | device extension             | nested target declare                                        | :good:`done`             | D51378                                                                |

clang/docs/analyzer/checkers.rst

 
 alpha.security
 ^^^^^^^^^^^^^^
 
 
 alpha.security.cert
 ^^^^^^^^^^^^^^^^^^^
 
-SEI CERT checkers which tries to find errors based on their `C coding rules<https://wiki.sei.cmu.edu/confluence/display/c/2+Rules>`_.
+SEI CERT checkers which tries to find errors based on their `C coding rules <https://wiki.sei.cmu.edu/confluence/display/c/2+Rules>`_.
 
 .. _alpha-security-cert-pos-checkers:
 
 alpha.security.cert.pos
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-SEI CERT checkers of POSIX `C coding rules<https://wiki.sei.cmu.edu/confluence/pages/viewpage.action?pageId=87152405>`_.
+SEI CERT checkers of `POSIX C coding rules <https://wiki.sei.cmu.edu/confluence/pages/viewpage.action?pageId=87152405>`_.
 
 .. _alpha-security-cert-pos-34c:
 
 alpha.security.cert.pos.34c
 """""""""""""""""""""""""""
 Finds calls to the ``putenv`` function which pass a pointer to an automatic variable as the argument.
 
 .. code-block:: c

clang/docs/analyzer/developer-docs/DebugChecks.rst

- ``void clang_analyzer_express(int);``
   See clang_analyzer_denote().
 
 - ``void clang_analyzer_isTainted(a single argument of any type);``
 
   Queries the analyzer whether the expression used as argument is tainted or not.
   This is useful in tests, where we don't want to issue warning for all tainted
   expressions but only check for certain expressions.
   This would help to reduce the *noise* that the `TaintTest` debug checker would
-  introduce and let you focus on the `expected-warning`s that you really care
+  introduce and let you focus on the `expected-warning`'s that you really care
   about.
 
   Example usage::
 
     int read_integer() {
       int n;
       clang_analyzer_isTainted(n);     // expected-warning{{NO}}
       scanf("%d", &n);

clang/include/clang/Basic/AttrDocs.td

where clause is one of the following:
   }];
 }
 
 def OMPDeclareVariantDocs : Documentation {
   let Category = DocCatFunction;
   let Heading = "#pragma omp declare variant";
   let Content = [{
 The `declare variant` directive declares a specialized variant of a base
- function and specifies the context in which that specialized variant is used.
- The declare variant directive is a declarative directive.
 The syntax of the `declare variant` construct is as follows:
 
   .. code-block:: none
 
     #pragma omp declare variant(variant-func-id) clause new-line
     [#pragma omp declare variant(variant-func-id) clause new-line]
     [...]
     function definition or declaration
 
 where clause is one of the following:
 
   .. code-block:: none
 
     match(context-selector-specification)
 
 and where `variant-func-id` is the name of a function variant that is either a
- base language identifier or, for C++, a template-id.
 
   }];
 }
 
 def NoStackProtectorDocs : Documentation {
   let Category = DocCatFunction;
   let Content = [{
 Clang supports the ``__attribute__((no_stack_protector))`` attribute which disables

 
 - If the receiver is ``nil``, the message send does nothing and returns the zero value
   for the return type.
 
 - A message send of a direct class method will cause the class to be initialized,
   including calling the ``+initialize`` method if present.
 
 - The implicit ``_cmd`` parameter containing the method's selector is still defined.
   In order to minimize code-size costs, the implementation will not emit a reference
   to the selector if the parameter is unused within the method.
 
 Symbols for direct method implementations are implicitly given hidden
 visibility, meaning that they can only be called within the same linkage unit.
 
 It is an error to do any of the following:
 
 - declare a direct method in a protocol,
 - declare an override of a direct method with a method in a subclass,
def LifetimeOwnerDocs : Documentation {
   let Category = DocCatDecl;
   let Content = [{
 .. Note:: This attribute is experimental and its effect on analysis is subject to change in
   a future version of clang.
 
 The attribute ``[[gsl::Owner(T)]]`` applies to structs and classes that own an
 object of type ``T``:
 
-.. code-block:: c++
+.. code::
 
   class [[gsl::Owner(int)]] IntOwner {
   private:
     int value;
   public:
     int *getInt() { return &value; }
   };
 
def LifetimePointerDocs : Documentation {
   let Category = DocCatDecl;
   let Content = [{
 .. Note:: This attribute is experimental and its effect on analysis is subject to change in
   a future version of clang.
 
 The attribute ``[[gsl::Pointer(T)]]`` applies to structs and classes that behave
 like pointers to an object of type ``T``:
 
-.. code-block:: c++
+.. code::
 
   class [[gsl::Pointer(int)]] IntPointer {
   private:
     int *valuePointer;
   public:
     int *getInt() { return &valuePointer; }
   };
 

 clang builtin functions.
   }];
 }
 
 def NoBuiltinDocs : Documentation {
   let Category = DocCatFunction;
   let Content = [{
 .. Note:: This attribute is not yet fully implemented, it is validated but has
           no effect on the generated code.
 
 The ``__attribute__((no_builtin))`` is similar to the ``-fno-builtin`` flag
 except it is specific to the body of a function. The attribute may also be
 applied to a virtual function but has no effect on the behavior of overriding
 functions in a derived class.
 
 It accepts one or more strings corresponding to the specific names of the
 builtins to disable (e.g. "memcpy", "memset").

clang/include/clang/Basic/DiagnosticGroups.td

 def FortifySource : DiagGroup<"fortify-source">;
 
 def MaxTokens : DiagGroup<"max-tokens"> {
   code Documentation = [{
 The warning is issued if the number of pre-processor tokens exceeds
 the token limit, which can be set in three ways:
 
 1. As a limit at a specific point in a file, using the ``clang max_tokens_here``
    pragma:
 
    .. code-block: c++
       #pragma clang max_tokens_here 1234
 
 2. As a per-translation unit limit, using the ``-fmax-tokens=`` command-line
    flag:
 
    .. code-block: console