Doc: Fix parameter inconsistencies

Author: Joseph-Edwards

docs/source/data-structures/words/to-string.rst

@@ -32,3 +32,4 @@ Full API
 .. autoclass:: ToString
     :class-doc-from: init
     :members:
+    :special-members: __call__

docs/source/data-structures/words/to-word.rst

@@ -32,3 +32,4 @@ Full API
 .. autoclass:: ToWord
     :class-doc-from: init
     :members:
+    :special-members: __call__

docs/source/main-algorithms/knuth-bendix/knuth-bendix.rst

@@ -54,7 +54,7 @@ Full API
     :members:
     :exclude-members: 
         options, run_for, run_until, run, finished, stopped, current_state, dead,
-        internal_generating_pairs, kill, last_report, report, report_every,
+        internal_generating_pairs, internal_presentation, kill, last_report, report, report_every,
         report_prefix, report_why_we_stopped, reset_last_report, reset_start_time,
         running, running_for, running_until, start_time, started, state,
         stopped_by_predicate, success, timed_out

etc/check-params.py

@@ -19,7 +19,7 @@ def warn(message):
     print(YELLOW + f"WARNING: {message}" + END_COLOUR)
 
 
-def extract_signature(func) -> tuple[dict[str, str], str]:
+def extract_signature(func, func_name) -> tuple[dict[str, str], str]:
     """Extract the parameters and typehints from the signature of a function
 
     This function interrogates the signature of a function and returns:
@@ -32,7 +32,7 @@ def extract_signature(func) -> tuple[dict[str, str], str]:
     for param in sig.find_all("em", class_="sig-param"):
         param_component = param.find_all("span", class_="n")
         if len(param_component) == 0 or len(param_component) > 2:
-            warn("unexpected element in doc. Skipping . . .")
+            warn(f"unexpected element in doc of {func_name}. Skipping . . .")
         elif len(param_component) == 1:
             param_to_typehint[param_component[0].get_text()] = ""
         else:
@@ -166,7 +166,7 @@ def process_file(filename):
             sig_block = sig_block.parent.find_parent("dl").find("dt")
         func_name = sig_block["id"]
 
-        sig_params, sig_return_typehint = extract_signature(func)
+        sig_params, sig_return_typehint = extract_signature(func, func_name)
         doc_params, doc_return_typehint = extract_documented_signature(func, func_name)
 
         compare_parameters(sig_params, doc_params, func_name)

src/action.cpp

@@ -221,14 +221,14 @@ Returns the number of generators.
                                      self.generators().cend());
           },
           R"pbdoc(
-:sig=(self: Action) -> Iterator[Element]:
+:sig=(self: Action) -> collections.abc.Iterator[Element]:
 
 Returns an iterator yielding the generators.
 
 :returns:
    An iterator yielding the generators.
 :rtype:
-   Iterator[Element]
+   collections.abc.Iterator[Element]
 
 :complexity:
    Constant.
@@ -405,7 +405,7 @@ of the strongly connected component containing ``self[pos]``.
           },
           py::arg("x"),
           R"pbdoc(
-:sig=(self: Action, x: Element) -> Point:
+:sig=(self: Action, x: Point) -> Point:
 
 Returns the root point of a strongly connected component containing an
 ``Point``.
@@ -428,7 +428,7 @@ Returns the root point of a strongly connected component containing an
           [](Action_& self, index_type pos) { return self.root_of_scc(pos); },
           py::arg("pos"),
           R"pbdoc(
-:sig=(self: Action, pos: Point) -> Point:
+:sig=(self: Action, pos: int) -> Point:
 
 Returns the root point of a strongly connected component.
 

src/aho-corasick.cpp

@@ -122,6 +122,7 @@ This function returns the index of the child of the node with index
               &AhoCorasick::height,
               py::arg("i"),
               R"pbdoc(
+:sig=(self: AhoCorasick, i: int) -> int:
 Calculate the height of a node.
 
 :param i: the index of the node whose height is sought
@@ -171,6 +172,8 @@ This function Returns the number of nodes in the trie.
         py::overload_cast<index_type>(&AhoCorasick::signature, py::const_),
         py::arg("i"),
         R"pbdoc(
+:sig=(self: AhoCorasick, i: int) -> list[int]:
+
 Find the signature of a node
 
 Return the the signature of the node with index *i*. Recall that the
@@ -190,6 +193,8 @@ the unique path from the root to :math:`n`.
               &AhoCorasick::suffix_link,
               py::arg("current"),
               R"pbdoc(
+:sig=(self: AhoCorasick, current: int) -> int:
+
 Calculate the index of the suffix link of a node.
 
 Calculate the index of a suffix link of a node. Recall that the *suffix link* of
@@ -215,6 +220,8 @@ the longest proper suffix of :math:`W` contained in the trie.
               py::arg("current"),
               py::arg("a"),
               R"pbdoc(
+:sig=(self: AhoCorasick, current: int, a: int) -> int:
+
 Traverse the trie using suffix links where necessary.
 
 This function traverses the trie using suffix links where necessary, behaving
@@ -244,6 +251,8 @@ trie.
               &AhoCorasick::throw_if_node_index_not_active,
               py::arg("i"),
               R"pbdoc(
+:sig=(self: AhoCorasick, i: int) -> None:
+
 Check if an index corresponds to a node currently in the trie.
 
 :param i: the index to validate
@@ -262,6 +271,8 @@ Check if an index corresponds to a node currently in the trie.
               &AhoCorasick::throw_if_node_index_out_of_range,
               py::arg("i"),
               R"pbdoc(
+:sig=(self: AhoCorasick, i: int) -> None:
+
 Check if an index corresponds to a node.
 
 This function checks if the given index *i* corresponds to the index of a
@@ -286,13 +297,18 @@ node; either active or inactive.
         },
         py::arg("i"),
         R"pbdoc(
+:sig=(self: AhoCorasick, i: int) -> bool:
+
 Check if a node is terminal (by index).
 
 This function checks if the node with index *i* is terminal or not.
 
 :param i: the index.
 :type i: int
 
+:returns: Whether or not the node is terminal
+:rtype: bool
+
 :raises LibsemigroupsError:
     if *i* does not correspond to the index of a node; that is, if *i* is
     larger than the size of the container storing the indices of nodes.

src/bipart.cpp

@@ -73,6 +73,8 @@ Copy a Blocks object.
               }),
               py::arg("blocks"),
               R"pbdoc(
+:sig=(self: Blocks, blocks: list[list[int]]) -> None:
+
 Constructs a Blocks object from a list of lists of integers.
 
 This function constructs a :any:`Blocks` object from a list of lists of
@@ -109,7 +111,7 @@ Return a const iterator yielding the indices of the blocks.
 :returns:
    An iterator yielding the indices of blocks.
 :rtype:
-   Iterator[int]
+   collections.abc.Iterator[int]
 
 :complexity:
    Constant.
@@ -135,6 +137,8 @@ the ``blocks`` used to construct *self*.
         },
         py::arg("index"),
         R"pbdoc(
+:sig=(self: Blocks, index: int) -> bool:
+
 Check if a block is a transverse block.
 
 This function returns ``True`` if the block with index *index* is a transverse
@@ -283,6 +287,8 @@ Copy a Bipartition object.
               }),
               py::arg("blocks"),
               R"pbdoc(
+:sig=(self: Bipartition, blocks: list[list[int]]) -> None:
+
 Construct a bipartition from a partition.
 
 The items in *blocks* should be:
@@ -303,6 +309,8 @@ The items in *blocks* should be:
               }),
               py::arg("lookup"),
               R"pbdoc(
+:sig=(self: Bipartition, lookup: list[int]) -> None:
+
 Construct a bipartition from a blocks lookup.
 
 The parameter *lookup*:
@@ -335,7 +343,7 @@ Return an iterator yielding the indices of the blocks.
 :returns:
    An iterator yielding the indices of the blocks.
 :rtype:
-   Iterator[int]
+   collections.abc.Iterator[int]
 
 :complexity:
    Constant.
@@ -359,6 +367,7 @@ A bipartition is of degree :math:`n` if it is a partition of
               &Bipartition::is_transverse_block,
               py::arg("index"),
               R"pbdoc(
+:sig=(self: Bipartition, index: int) -> bool:
 Check if a block is a transverse block.
 
 A block of a biparition is *transverse* if it contains integers less than and
@@ -494,6 +503,8 @@ are referred to as the *transverse* blocks.
                      &Bipartition::one,
                      py::arg("n"),
                      R"pbdoc(
+:sig=(self: Bipartition, n: int) -> Bipartition:
+
 Return the identity bipartition of given degree.
 
 Returns the identity bipartition of degree ``n``. The *identity bipartition* of

src/bmat8.cpp

@@ -166,6 +166,8 @@ There is no guarantee about the contents of the matrix constructed.
     thing.def(py::init<uint64_t>(),
               py::arg("val"),
               R"pbdoc(
+:sig=(self: BMat8, val: int) -> None:
+
 Construct from ``int``.
 
 This constructor initializes a :any:`BMat8` to have rows equal to the 8 chunks,
@@ -178,10 +180,12 @@ of 8 bits each, of the binary representation of ``mat``.
     thing.def(py::init<std::vector<std::vector<bool>> const&>(),
               py::arg("rows"),
               R"pbdoc(
+:sig=(self: BMat8, rows: list[list[bool]]) -> None:
+
 Construct from list of rows.
 
 This constructor initializes a matrix where the rows of the matrix are the
-lists in ``rows``.
+lists in *rows*.
 
 :param rows: the list of rows of the matrix being constructed.
 :type rows: list[list[bool]]
@@ -191,7 +195,15 @@ lists in ``rows``.
 :raises LibsemigroupsError:  if the rows of *rows* are not all of the same length.
 
 :complexity: Constant.)pbdoc");
-    thing.def("degree", [](BMat8 const& self) { return 8; });
+    thing.def(
+        "degree", [](BMat8 const& self) { return 8; }, R"pbdoc(
+Returns the degree of *self*.
+
+This function always returns ``8``.
+
+:returns: The degree of the matrisx, ``8``.
+:rtype: int
+)pbdoc");
 
     thing.def(
         "copy",
@@ -459,7 +471,7 @@ Returns the size of the row space of a :any:`BMat8`.
 :param x: the matrix.
 :type x: BMat8
 
-:returns: The size of the row space of ``x``.
+:returns: The size of the row space of *x*.
 :rtype: int
 
 :complexity:  :math:`O(n)` where :math:`n` is the return value of this function.
@@ -505,7 +517,7 @@ Returns the size of the column space of a :any:`BMat8`.
 :sig=(x: BMat8) -> int:
 Returns the minimum dimension of a :any:`BMat8`.
 
-This function returns the maximal ``n`` such that row ``n`` or column ``n`` in
+This function returns the maximal *n* such that row *n* or column *n* in
 the boolean matrix *x* contains a ``1``. Equivalent to the maximum of
 :any:`number_of_rows` and :any:`number_of_cols`.
 

src/cong-common.cpp

@@ -1121,7 +1121,7 @@ instance *{var}*.
         },
         py::arg(extra_doc.var.data()),
         make_doc(R"pbdoc(
-:sig=({var}: {name}) -> Iterator[str | list[int]]:
+:sig=({var}: {name}) -> collections.abc.Iterator[str | list[int]]:
 {only_document_once}
 
 Returns an iterator yielding normal forms.
@@ -1135,7 +1135,7 @@ the congruence represented by an instance of :any:`{name}`.
 :type {var}: {name}
 
 :returns: An iterator yielding normal forms.
-:rtype: Iterator[str | list[int]]
+:rtype: collections.abc.Iterator[str | list[int]]
 
 {raises}
 

src/dot.cpp

@@ -231,9 +231,9 @@ This function adds a node with name *name*.
 This function adds an edge from the node named *head* to the node named *tail*.
 
 :param head: the name of the node at the head of the edge.
-:type name: str
+:type head: str
 :param tail: the name of the node at the tail of the edge.
-:type name: str
+:type tail: str
 
 :returns: a newly created :any:`Dot.Edge` object.
 :rtype: Dot.Edge