RestructuredText documentation fixes

Fixed by using docdiffer.sh to identify documentation regressions

5 files changed, 400 insertions, 277 deletions

diff --git a/SphinxDocs/source/Manual/CPlusPlus11.rst b/SphinxDocs/source/Manual/CPlusPlus11.rst
index 6133ce466..85b54327c 100644
--- a/SphinxDocs/source/Manual/CPlusPlus11.rst
+++ b/SphinxDocs/source/Manual/CPlusPlus11.rst
@@ -903,7 +903,7 @@ Static assertions
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 SWIG correctly parses the new ``static_assert`` declarations (though
-and earlier had a bug which meant this wasn't accepted at file
+3.0.12 and earlier had a bug which meant this wasn't accepted at file
 scope). This is a C++ compile time directive so there isn't anything
 useful that SWIG can do with it.
 
diff --git a/SphinxDocs/source/Manual/CSharp.rst b/SphinxDocs/source/Manual/CSharp.rst
index 3dbaa0a58..ed32a4d77 100644
--- a/SphinxDocs/source/Manual/CSharp.rst
+++ b/SphinxDocs/source/Manual/CSharp.rst
@@ -58,19 +58,21 @@ for the C# module. They can also be seen by using:
 
       swig -csharp -help 
 
-+---------------------+
-| C# specific options |
-+=====================+
-| -dllimport <dl>     |
-+---------------------+
-| -namespace <nm>     |
-+---------------------+
-| -noproxy            |
-+---------------------+
-| -oldvarnames        |
-+---------------------+
-| -outfile <file>     |
-+---------------------+
++---------------------+---------------------------------------------------------+
+| C# specific options |                                                         |
++=====================+=========================================================+
+| -dllimport <dl>     | Override DllImport attribute name to <dl>               |
++---------------------+---------------------------------------------------------+
+| -namespace <nm>     | Generate wrappers into C# namespace <nm>                |
++---------------------+---------------------------------------------------------+
+| -noproxy            | Generate the low-level functional interface instead of  |
+|                     | proxy classes                                           |
++---------------------+---------------------------------------------------------+
+| -oldvarnames        | Old intermediary method names for variable wrappers     |
++---------------------+---------------------------------------------------------+
+| -outfile <file>     | Write all C# into a single <file> located in the output |
+|                     | directory                                               |
++---------------------+---------------------------------------------------------+
 
 The -outfile option combines all the generated C# code into a single
 output file instead of creating multiple C# files. The default, when
@@ -141,6 +143,7 @@ differences to Java are the following:
 
 -  The default enum wrapping approach is proper C# enums, not typesafe
    enums.
+
    Note that %csconst(0) will be ignored when wrapping C/C++ enums with
    proper C# enums. This is because C# enum items must be initialised
    from a compile time constant. If an enum item has an initialiser and
@@ -462,14 +465,14 @@ differences to Java are the following:
    of ensuring a reference to the proxy class is held until the
    unmanaged call completed.
 
-| **``$dllimport``**
+| **$dllimport**
 | This is a C# only special variable that can be used in typemaps,
   pragmas, features etc. The special variable will get translated into
   the value specified by the ``-dllimport`` commandline option if
   specified, otherwise it is equivalent to the **$module** special
   variable.
 
-| **``$imclassname``**
+| **$imclassname**
 | This special variable expands to the intermediary class name. For C#
   this is usually the same as '$modulePINVOKE' ('$moduleJNI' for Java),
   unless the imclassname attribute is specified in the `%module
diff --git a/SphinxDocs/source/Manual/Chicken.rst b/SphinxDocs/source/Manual/Chicken.rst
index 34238f8ee..078caba95 100644
--- a/SphinxDocs/source/Manual/Chicken.rst
+++ b/SphinxDocs/source/Manual/Chicken.rst
@@ -110,7 +110,7 @@ The generated example.scm file then exports
 ``(declare (unit modulename))``, pass the -nounit option to SWIG.
 
 CHICKEN will be able to access the module using the
-``(declare         (uses modulename))`` CHICKEN Scheme form.
+``(declare (uses modulename))`` CHICKEN Scheme form.
 
 Constants and Variables
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -121,7 +121,7 @@ interface file:
 #. ``#define MYCONSTANT1 ...``
 #. ``%constant int MYCONSTANT2 = ...``
 #. ``const int MYCONSTANT3 = ...``
-#. ``enum { MYCONSTANT4  = ... };``
+#. ``enum { MYCONSTANT4 = ... };``
 
 In all cases, the constants may be accessed from within CHICKEN using
 the form ``(MYCONSTANT1)``; that is, the constants may be accessed using
@@ -238,8 +238,8 @@ Linkage
 Please refer to *CHICKEN - A practical and portable Scheme system -
 User's manual* for detailed help on how to link object files to create a
 CHICKEN Scheme program. Briefly, to link object files, be sure to add
-:literal:`\`chicken-config       -extra-libs -libs\`` or
-:literal:`\`chicken-config -shared       -extra-libs -libs\``\ to your
+:literal:`\`chicken-config -extra-libs -libs\`` or
+:literal:`\`chicken-config -shared -extra-libs -libs\``\ to your
 linker options. Use the ``-shared`` option if you want to create a
 dynamically loadable module. You might also want to use the much simpler
 ``csc`` or ``csc.bat``.
@@ -444,8 +444,8 @@ object might get deleted while the scheme code still holds a pointer to
 it. Further use of this pointer can lead to a crash.
 
 Adding a finalizer function from C code was added to chicken in the 1.89
-release, so garbage collection does not work for chicken versions below
-If you would like the SWIG generated code to work with chicken
+release, so garbage collection does not work for chicken versions below 1.89.
+If you would like the SWIG generated code to work with chicken 1.40
 to 1.89, pass the ``-nocollection`` argument to SWIG. This will not
 export code inside the \_wrap.c file to register finalizers, and will
 then export destructor functions which must be called manually.
diff --git a/SphinxDocs/source/Manual/D.rst b/SphinxDocs/source/Manual/D.rst
index 3a3784309..b1d43eacf 100644
--- a/SphinxDocs/source/Manual/D.rst
+++ b/SphinxDocs/source/Manual/D.rst
@@ -158,7 +158,7 @@ the return type used in the intermediary D module to the type returned
 by the proxy function. The ``$excode`` special variable in ``dout``
 typemaps is replaced by the ``excode`` typemap attribute code if the
 method can throw any exceptions from unmanaged code, otherwise by
-nothing (the ```$imcall`` and ``$owner`` <D.html#D_imcall>`__ macros are
+nothing (the `$imcall and $owner <D_imcall_>`_ macros are
 replaced).
 
 The code from the ``ddirectorin`` and ``ddirectorout`` typemaps is used
@@ -290,6 +290,8 @@ When generating D wrappers, a few additional macros are available:
            example_im.foo(SomeClass.getCPointer(arg));
          }
 
+.. _D_imcall:
+
 ``$imcall`` and ``$owner`` (C#: ``$imcall``)
    These variables are used in ``dout`` typemaps. ``$imcall`` contains
    the call to the intermediary module which provides the value to be
diff --git a/SphinxDocs/source/Manual/Doxygen.rst b/SphinxDocs/source/Manual/Doxygen.rst
index 46c276302..f3668bd13 100644
--- a/SphinxDocs/source/Manual/Doxygen.rst
+++ b/SphinxDocs/source/Manual/Doxygen.rst
@@ -457,10 +457,10 @@ the SWIG generated code.
 
 The Javadoc translator will handle most of the tags conversions (see the
 table below). It will also automatically translate link-objects params,
-in \\see and \\link...\endlink commands. For example,
+in \\see and \\link...\\endlink commands. For example,
 'someFunction(std::string)' will be converted to 'someFunction(String)'.
 If you don't want such behaviour, you could turn this off by using the
-'doxygen:nolinktranslate' feature. Also all '\param' and '\tparam'
+'doxygen:nolinktranslate' feature. Also all '\\param' and '\\tparam'
 commands are stripped out, if the specified parameter is not present in
 the function. Use 'doxygen:nostripparams' to avoid.
 
@@ -473,135 +473,195 @@ Javadoc tags
 Here is the list of all Doxygen tags and the description of how they are
 translated to Javadoc
 
-.. container:: diagram
+.. list-table:: Java Doxygen Tags
+    :widths: 20 80
+
+    * - \\a
+      - wrapped with <i> html tag
+
+    * - \\arg
+      - wrapped with <li> html tag
+
+    * - \\author
+      - translated to @author
+
+    * - \\authors
+      - translated to @author
+
+    * - \\b
+      - wrapped with <b> html tag
+
+    * - \\c
+      - wrapped with <code> html tag
+
+    * - \\cite
+      - wrapped with <i> html tag
+
+    * - \\code
+      - translated to {\@code ...}
+
+    * - \\code{<ext>}
+      - translated to {\@code ...}; code language extension is ignored
+
+    * - \\cond
+      - translated to 'Conditional comment: <condition>'
+
+    * - \\copyright
+      - replaced with 'Copyright:'
+
+    * - \\deprecated
+      - translated to @deprecated
+
+    * - \\e
+      - wrapped with <i> html tag
+
+    * - \\else
+      - replaced with '}Else:{'
+
+    * - \\elseif
+      - replaced with '}Else if: <condition>{'
+
+    * - \\em
+      - wrapped with <i> html tag
+
+    * - \\endcode
+      - see note for \\code
+
+    * - \\endcond
+      - replaced with 'End of conditional comment.'
+
+    * - \\endif
+      - replaced with '}'
+
+    * - \\endlink
+      - see note for \\link
+
+    * - \\endverbatim
+      - see note for \\verbatim
+
+    * - \\exception
+      - translated to @exception
+
+    * - \\f$, \\f[, \\f], \\f{, \\f}
+      - LateX formulas are left unchanged
+
+    * - \\if
+      - replaced with 'If: <condition> {'
+
+    * - \\ifnot
+      - replaced with 'If not: <condition> {'
+
+    * - \\image
+      - translated to <img/> html tag only if target=HTML
+
+    * - \\li
+      - wrapped with <li> html tag
+
+    * - \\link
+      - translated to {\@link ...}
+
+    * - \\n
+      - replaced with newline char
+
+    * - \\note
+      - replaced with 'Note:'
+
+    * - \\overload
+      - prints 'This is an overloaded ...' according to Doxygen docs
+
+    * - \\p
+      - wrapped with <code> html tag
+
+    * - \\par
+      - replaced with <p alt='title'>...</p>
+
+    * - \\param
+      - translated to @param
+
+    * - \\param[<dir>]
+      - translated to @param; parameter direction ('in'; 'out'; or 'in,out') is ignored
+
+    * - \\remark
+      - replaced with 'Remarks:'
+
+    * - \\remarks
+      - replaced with 'Remarks:'
+
+    * - \\result
+      - translated to @return
+
+    * - \\return
+      - translated to @return
+
+    * - \\returns
+      - translated to @return
+
+    * - \\sa
+      - translated to @see
+
+    * - \\see
+      - translated to @see
+
+    * - \\since
+      - translated to @since
+
+    * - \\throw
+      - translated to @throws
+
+    * - \\throws
+      - translated to @throws
+
+    * - \\todo
+      - replaced with 'TODO:'
+
+    * - \\tparam
+      - translated to @param
+
+    * - \\verbatim
+      - translated to {\@literal ...}
+
+    * - \\version
+      - translated to @version
+
+    * - \\warning
+      - translated to 'Warning:'
+
+    * - \\$
+      - prints $ char
+
+    * - \\@
+      - prints @ char
+
+    * - ``\\``
+      - prints \\ char
+
+    * - \\&
+      - prints & char
+
+    * - \\~
+      - prints ~ char
+
+    * - \\<
+      - prints < char
+
+    * - \\>
+      - prints > char
+
+    * - \\#
+      - prints # char
+
+    * - \\%
+      - prints % char
+
+    * - \\"
+      - prints " char
+
+    * - \\.
+      - prints . char
+
+    * - \\\:\:
+      - prints \:\:
 
-   +------------------------------+
-   | Doxygen tags                 |
-   +==============================+
-   | \\a                          |
-   +------------------------------+
-   | \\arg                        |
-   +------------------------------+
-   | \\author                     |
-   +------------------------------+
-   | \\authors                    |
-   +------------------------------+
-   | \\b                          |
-   +------------------------------+
-   | \\c                          |
-   +------------------------------+
-   | \\cite                       |
-   +------------------------------+
-   | \\code                       |
-   +------------------------------+
-   | \\code{<ext>}                |
-   +------------------------------+
-   | \\cond                       |
-   +------------------------------+
-   | \\copyright                  |
-   +------------------------------+
-   | \\deprecated                 |
-   +------------------------------+
-   | \\e                          |
-   +------------------------------+
-   | \\else                       |
-   +------------------------------+
-   | \\elseif                     |
-   +------------------------------+
-   | \\em                         |
-   +------------------------------+
-   | \\endcode                    |
-   +------------------------------+
-   | \\endcond                    |
-   +------------------------------+
-   | \\endif                      |
-   +------------------------------+
-   | \\endlink                    |
-   +------------------------------+
-   | \\endverbatim                |
-   +------------------------------+
-   | \\exception                  |
-   +------------------------------+
-   | \\f$, \\f[, \\f], \\f{, \\f} |
-   +------------------------------+
-   | \\if                         |
-   +------------------------------+
-   | \\ifnot                      |
-   +------------------------------+
-   | \\image                      |
-   +------------------------------+
-   | \\li                         |
-   +------------------------------+
-   | \\link                       |
-   +------------------------------+
-   | \\n                          |
-   +------------------------------+
-   | \\note                       |
-   +------------------------------+
-   | \\overload                   |
-   +------------------------------+
-   | \\p                          |
-   +------------------------------+
-   | \\par                        |
-   +------------------------------+
-   | \\param                      |
-   +------------------------------+
-   | \\param[<dir>]               |
-   +------------------------------+
-   | \\remark                     |
-   +------------------------------+
-   | \\remarks                    |
-   +------------------------------+
-   | \\result                     |
-   +------------------------------+
-   | \\return                     |
-   +------------------------------+
-   | \\returns                    |
-   +------------------------------+
-   | \\sa                         |
-   +------------------------------+
-   | \\see                        |
-   +------------------------------+
-   | \\since                      |
-   +------------------------------+
-   | \\throw                      |
-   +------------------------------+
-   | \\throws                     |
-   +------------------------------+
-   | \\todo                       |
-   +------------------------------+
-   | \\tparam                     |
-   +------------------------------+
-   | \\verbatim                   |
-   +------------------------------+
-   | \\version                    |
-   +------------------------------+
-   | \\warning                    |
-   +------------------------------+
-   | \\$                          |
-   +------------------------------+
-   | \\@                          |
-   +------------------------------+
-   | \\\\                         |
-   +------------------------------+
-   | \\&                          |
-   +------------------------------+
-   | \\~                          |
-   +------------------------------+
-   | \\<                          |
-   +------------------------------+
-   | \\>                          |
-   +------------------------------+
-   | \\#                          |
-   +------------------------------+
-   | \\%                          |
-   +------------------------------+
-   | \\"                          |
-   +------------------------------+
-   | \\.                          |
-   +------------------------------+
-   | \\::                         |
-   +------------------------------+
 
 Unsupported tags
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -944,131 +1004,189 @@ Pydoc translator
 Here is the list of all Doxygen tags and the description of how they are
 translated to Pydoc
 
-.. container:: diagram
+.. list-table:: Python Doxygen tags
+    :widths: 20 80
+
+    * - \\a
+      - wrapped with '*'
+
+    * - \\arg
+      - prepended with '* '
+
+    * - \\author
+      - prints 'Author:'
+
+    * - \\authors
+      - prints 'Authors:'
+
+    * - \\b
+      - wrapped with '**'
+
+    * - \\c
+      - wrapped with '``'
+
+    * - \\cite
+      - wrapped with single quotes
+
+    * - \\code
+      - replaced with '.. code-block:: c++'
+
+    * - \\code{<ext>}
+      - replaced with '.. code-block:: <lang>', where the following doxygen code languages are recognized: .c -> C, .py -> python, .java > java
+
+    * - \\cond
+      - translated to 'Conditional comment: <condition>'
+
+    * - \\copyright
+      - prints 'Copyright:'
+
+    * - \\deprecated
+      - prints 'Deprecated:'
+
+    * - \\e
+      - wrapped with '*'
+
+    * - \\else
+      - replaced with '}Else:{'
+
+    * - \\elseif
+      - replaced with '}Else if: <condition>{'
+
+    * - \\em
+      - wrapped with '*'
+
+    * - \\endcond
+      - replaced with 'End of conditional comment.'
+
+    * - \\endif
+      - replaced with '}'
+
+    * - \\example
+      - replaced with 'Example:'
+
+    * - \\exception
+      - replaced with ':raises:'
+
+    * - \\f$
+      - rendered using ':math:\`\`'
+
+    * - \\f[
+      - rendered using '.. math::'
+
+    * - \\f{
+      - rendered using '.. math::'
+
+    * - \\if
+      - replaced with 'If: <condition> {'
+
+    * - \\ifnot
+      - replaced with 'If not: <condition> {'
+
+    * - \\li
+      - prepended with '* '
+
+    * - \\n
+      - replaced with newline char
+
+    * - \\note
+      - replaced with 'Note:'
+
+    * - \\overload
+      - prints 'This is an overloaded ...' according to Doxygen docs
+
+    * - \\p
+      - wrapped with '``'
+
+    * - \\par
+      - replaced with 'Title: ...'
+
+    * - \\param
+      - add ':type:' and ':param:' directives
+
+    * - \\param[<dir>]
+      - same as \\param, but direction ('in'; 'out'; 'in,out') is included in ':type:' directive
+
+    * - \\remark
+      - replaced with 'Remarks:'
+
+    * - \\remarks
+      - replaced with 'Remarks:'
+
+    * - \\result
+      - add ':rtype:' and ':return:' directives
+
+    * - \\return
+      - add ':rtype:' and ':return:' directives
+
+    * - \\returns
+      - add ':rtype:' and ':return:' directives
+
+    * - \\sa
+      - replaced with 'See also:'
+
+    * - \\see
+      - replaced with 'See also:'
+
+    * - \\since
+      - replaced with 'Since:'
+
+    * - \\throw
+      - replaced with ':raises:'
+
+    * - \\throws
+      - replaced wih ':raises:'
+
+    * - \\todo
+      - replaced with 'TODO:'
+
+    * - \\tparam
+      - add ':type:' and ':param:' directives
+
+    * - \\verbatim
+      - content copied verbatim
+
+    * - \\version
+      - replaced with 'Version:'
+
+    * - \\warning
+      - translated to 'Warning:'
+
+    * - \\$
+      - prints $ char
+
+    * - \\@
+      - prints @ char
+
+    * - ``\\``
+      - prints \\ char
+
+    * - \\&
+      - prints & char
+
+    * - \\~
+      - prints ~ char
+
+    * - \\<
+      - prints < char
+
+    * - \\>
+      - prints > char
+
+    * - \\#
+      - prints # char
+
+    * - \\%
+      - prints % char
+
+    * - \\"
+      - prints " char
+
+    * - \\.
+      - prints . character
+
+    * - \\\:\:
+      - prints \:\:
 
-   +----------------+
-   | Doxygen tags   |
-   +================+
-   | \\a            |
-   +----------------+
-   | \\arg          |
-   +----------------+
-   | \\author       |
-   +----------------+
-   | \\authors      |
-   +----------------+
-   | \\b            |
-   +----------------+
-   | \\c            |
-   +----------------+
-   | \\cite         |
-   +----------------+
-   | \\code         |
-   +----------------+
-   | \\code{<ext>}  |
-   +----------------+
-   | \\cond         |
-   +----------------+
-   | \\copyright    |
-   +----------------+
-   | \\deprecated   |
-   +----------------+
-   | \\e            |
-   +----------------+
-   | \\else         |
-   +----------------+
-   | \\elseif       |
-   +----------------+
-   | \\em           |
-   +----------------+
-   | \\endcond      |
-   +----------------+
-   | \\endif        |
-   +----------------+
-   | \\example      |
-   +----------------+
-   | \\exception    |
-   +----------------+
-   | \\f$           |
-   +----------------+
-   | \\f[           |
-   +----------------+
-   | \\f{           |
-   +----------------+
-   | \\if           |
-   +----------------+
-   | \\ifnot        |
-   +----------------+
-   | \\li           |
-   +----------------+
-   | \\n            |
-   +----------------+
-   | \\note         |
-   +----------------+
-   | \\overload     |
-   +----------------+
-   | \\p            |
-   +----------------+
-   | \\par          |
-   +----------------+
-   | \\param        |
-   +----------------+
-   | \\param[<dir>] |
-   +----------------+
-   | \\remark       |
-   +----------------+
-   | \\remarks      |
-   +----------------+
-   | \\result       |
-   +----------------+
-   | \\return       |
-   +----------------+
-   | \\returns      |
-   +----------------+
-   | \\sa           |
-   +----------------+
-   | \\see          |
-   +----------------+
-   | \\since        |
-   +----------------+
-   | \\throw        |
-   +----------------+
-   | \\throws       |
-   +----------------+
-   | \\todo         |
-   +----------------+
-   | \\tparam       |
-   +----------------+
-   | \\verbatim     |
-   +----------------+
-   | \\version      |
-   +----------------+
-   | \\warning      |
-   +----------------+
-   | \\$            |
-   +----------------+
-   | \\@            |
-   +----------------+
-   | \\\\           |
-   +----------------+
-   | \\&            |
-   +----------------+
-   | \\~            |
-   +----------------+
-   | \\<            |
-   +----------------+
-   | \\>            |
-   +----------------+
-   | \\#            |
-   +----------------+
-   | \\%            |
-   +----------------+
-   | \\"            |
-   +----------------+
-   | \\.            |
-   +----------------+
-   | \\::           |
-   +----------------+
 
 .. _unsupported-tags-1: