Param doc

etc/check_params_doc.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+
+import re
+import os
+from os import listdir
+from os.path import isfile, splitext
+
+begin_warn_col = "\033[93m"
+end_warn_col = "\033[0m"
+
+
+def all_cpp_files(start):
+    files = set()
+
+    def dive(path):
+        for entry in listdir(path):
+            candidate = os.path.join(path, entry)
+            if isfile(candidate) and splitext(entry)[1] == ".cpp":
+                files.add(candidate)
+            elif not isfile(candidate):
+                dive(candidate)
+
+    dive(start)
+    return files
+
+
+src_path = "src"
+files = all_cpp_files(src_path)
+
+param_pattern = re.compile(r":param (\w+):")
+
+print("Checking docstring indentation in .cpp files . . .")
+for file in files:
+    with open(file, "r") as f:
+        line_is_doc = False
+        for line_no, line in enumerate(f):
+            if line_is_doc and ")pbdoc" in line:
+                line_is_doc = False
+            if not line_is_doc and "pbdoc(" in line:
+                params = []
+                line_is_doc = True
+            if not line_is_doc:
+                continue
+            match = param_pattern.match(line)
+            if match:
+                params.append(match.group(1))
+            for param in params:
+                if f"``{param}``" in line:
+                    print(
+                        f"{begin_warn_col}Warning: found ``{param}`` "
+                        f"in {file}:{line_no + 1}{end_warn_col}"
+                    )

src/action.cpp

@@ -121,7 +121,7 @@ In this documentation we refer to:
 
 Copy an :any:`Action`.
 
-:returns: A copy of the ``self``.
+:returns: A copy of the *self*.
 :rtype: Action
 )pbdoc");
 
@@ -133,7 +133,7 @@ Copy an :any:`Action`.
 Re-initialize an existing object. This function puts an action object back into
 the same state as if it had been newly default constructed.
 
-:returns: ``self``.
+:returns: *self*.
 :rtype: Action
 )pbdoc");
       thing.def("reserve",
@@ -147,12 +147,12 @@ Increase the capacity to a value that is greater or equal to *val*.
 :param val: new capacity of an action instance.
 :type val: int
 
-:raises MemoryError:  if ``val`` is too large.
+:raises MemoryError:  if *val* is too large.
 
 :complexity:
   At most linear in the :any:`size()` of the :py:class:`Action`.
 
-:returns: ``self``.
+:returns: *self*.
 :rtype: Action
 )pbdoc");
       thing.def("add_seed",
@@ -172,7 +172,7 @@ generators of the action.
 
 :complexity: Constant.
 
-:returns: ``self``
+:returns: *self*
 :rtype: Action
 )pbdoc");
       thing.def("add_generator",
@@ -191,7 +191,7 @@ generated by the elements added via this member function.
 
 :complexity: Constant.
 
-:returns: ``self``.
+:returns: *self*.
 :rtype: Action
 )pbdoc");
       thing.def("number_of_generators",
@@ -245,7 +245,7 @@ Returns the position of a point in the so far discovered points.
 
 :complexity: Constant.
 
-:returns: The index of *pt* in ``self`` or :any:`UNDEFINED`.
+:returns: The index of *pt* in *self* or :any:`UNDEFINED`.
 :rtype: int | Undefined
 )pbdoc");
       thing.def("empty",
@@ -340,7 +340,7 @@ cached, and not recomputed every time one of these functions is called.
 
 :complexity: Constant.
 
-:returns: ``self``.
+:returns: *self*.
 :rtype: Action
 )pbdoc");
       thing.def("multiplier_from_scc_root",

src/aho-corasick.cpp

@@ -149,7 +149,7 @@ if it had been newly default constructed.
 
 :complexity: Linear in the number of nodes in the trie
 
-:returns: ``self``.
+:returns: *self*.
 :rtype: AhoCorasick
 )pbdoc");
 

src/bipart.cpp

@@ -83,7 +83,7 @@ transverse and those consisting of positive values are not.
 :type blocks: list
 
 :raises LibsemigroupsError:
-  if the set consisting of the absolute values of the entries in ``blocks`` is
+  if the set consisting of the absolute values of the entries in *blocks* is
   not :math:`\{1, \ldots, n\}` where :math:`n` is the maximum such value.
 
 :raises LibsemigroupsError:  if ``0`` is an item in any block.
@@ -120,7 +120,7 @@ Return a const iterator yielding the indices of the blocks.
               R"pbdoc(
 Return the degree of a blocks object. The *degree* of a :any:`Blocks`
 object is the size of the set of which it is a partition, or the size of
-the ``blocks`` used to construct ``self``.
+the ``blocks`` used to construct *self*.
 
 :returns:
    The degree of a :any:`Blocks` object.
@@ -197,7 +197,7 @@ of ``True`` values in :any:`lookup()`.
    At most linear in the number of blocks.
 
 :returns:
-   The number of signed (transverse) blocks in ``self``.
+   The number of signed (transverse) blocks in *self*.
 :rtype:
    int
 )pbdoc");
@@ -534,7 +534,7 @@ Return the identity bipartition with the same degree as the given bipartition.
 
 The *identity bipartition* of degree :math:`n` has blocks :math:`\{i, -i\}` for
 all :math:`i\in \{0, \ldots, n - 1\}`. This function returns a new identity
-bipartition of degree equal to the degree of ``self``.
+bipartition of degree equal to the degree of *self*.
 
 :param f: a bipartition
 :type f: Bipartition

src/cong-common.cpp

@@ -158,7 +158,7 @@ have been in if it had just been newly default constructed.
 {detail}
 
 :returns:
-  ``self``.
+  *self*.
 :rtype:
     {name})pbdoc",
                  name,
@@ -304,7 +304,7 @@ had been newly constructed from *knd* and *p*.
 :param p: the presentation.
 :type p: Presentation
 
-:returns:  ``self``.
+:returns:  *self*.
 :rtype: {name}
 
 :raises LibsemigroupsError: if *p* is not valid.
@@ -489,7 +489,7 @@ This function adds a generating pair to the congruence represented by a
 :param v: the second item in the pair.
 :type v: list[int] | str
 
-:returns: ``self``.
+:returns: *self*.
 :rtype: {name}
 
 :raises LibsemigroupsError:
@@ -1169,7 +1169,7 @@ the congruence represented by an instance of :any:`{name}`.
 
 The kind of the congruence (1- or 2-sided).
 
-This function returns the kind of the congruence represented by ``self``. See
+This function returns the kind of the congruence represented by *self*. See
 :any:`congruence_kind` for details.
 
 :complexity:

src/cong.cpp

@@ -117,7 +117,7 @@ Set the maximum number of threads.
 :param val: the number of threads.
 :type val: int
 
-:returns: ``self``.
+:returns: *self*.
 :rtype: Congruence
 )pbdoc");
 

src/dot.cpp

@@ -89,7 +89,7 @@ attribute of a :any:`Dot.Node`.
 :param val: the value of the attribute.
 :type val: str
 
-:returns: ``self``
+:returns: *self*
 :rtype: Dot.Node
 )pbdoc",
           py::return_value_policy::reference);
@@ -136,7 +136,7 @@ attribute of an :any:`Edge`.
 :param val: the value of the attribute.
 :type val: str
 
-:returns: ``self``
+:returns: *self*
 :rtype: Dot.Edge
 )pbdoc");
 
@@ -257,7 +257,7 @@ This function adds an edge from the node named *head* to the node named *tail*.
         // last edge reference is collected.
         py::arg("subgraph"),
         R"pbdoc(
-This functions adds the :any:`Dot` object *subgraph* as a subgraph of ``self``.
+This functions adds the :any:`Dot` object *subgraph* as a subgraph of *self*.
 The following transformations are performed
 
 * the ``label`` attribute of the added subgraph is the :any:`Dot.name` of
@@ -275,7 +275,7 @@ The following transformations are performed
 :param subgraph: the :any:`Dot` object to use as a subgraph.
 :type subgraph: Dot
 
-:returns: ``self``.
+:returns: *self*.
 :rtype: Dot
 )pbdoc");
 
@@ -348,7 +348,7 @@ Set the kind of the represented graph.
    Dot.Kind
 
 :returns:
-   ``self``.
+   *self*.
 :rtype:
    Dot
 )pbdoc");
@@ -391,7 +391,7 @@ Set the name of the represented graph.
    str
 
 :returns:
-   ``self``.
+   *self*.
 :rtype:
    Dot
 )pbdoc");
@@ -472,7 +472,7 @@ representation of the graph in the `DOT
 <https://www.graphviz.org>`_.
 
 :returns:
-   The string representation of ``self``.
+   The string representation of *self*.
 :rtype:
    str
 )pbdoc");
@@ -491,7 +491,7 @@ attribute of an :any:`Dot`.
 :param val: the value of the attribute.
 :type val: str
 
-:returns: ``self``
+:returns: *self*
 :rtype: Dot
 )pbdoc",
             py::return_value_policy::reference);
@@ -507,7 +507,7 @@ attribute of an :any:`Dot`.
 :param key: the name of the attribute.
 :type key: str
 
-:returns: ``self``
+:returns: *self*
 :rtype: Dot
 )pbdoc",
             py::return_value_policy::reference);

src/forest.cpp

@@ -140,7 +140,7 @@ the same state as if it had just be constructed as ``Forest(n)``.
 :param n: the number of nodes, defaults to ``0``.
 :type n: int
 
-:returns: ``self``.
+:returns: *self*.
 :rtype: Forest
 )pbdoc");
 
@@ -194,9 +194,9 @@ Returns the label of the edge from a node to its parent.
 :sig=(self: Forest) -> list[int | Undefined]:
 
 Returns a copy of the list of edge labels in the :any:`Forest`. The value
-in position ``i`` of this list is the label of the edge from the
-parent of node ``i`` to ``i``. If the parent equals :any:`UNDEFINED`,
-then node ``i`` is a root node.
+in position *i* of this list is the label of the edge from the
+parent of node *i* to *i*. If the parent equals :any:`UNDEFINED`,
+then node *i* is a root node.
 
 :returns:
    The edge labels of the forest.
@@ -323,7 +323,7 @@ Set the parent and edge label for a node. This function sets the parent of
 :param gen: the label of the edge from parent to node.
 :type gen: int
 
-:returns: ``self``
+:returns: *self*
 :rtype: Forest
 
 :raises LibsemigroupsError: