From b65bff588c6f1302dec1287497c7c28bd5775c9e Mon Sep 17 00:00:00 2001
From: reiniscirpons <rc234@st-andrews.ac.uk>
Date: Mon, 4 Nov 2024 18:28:29 +0000
Subject: [PATCH] Small documentation improvements, and missing function
 implementation, from python bindings

---
 include/libsemigroups/sims.hpp | 48 ++++++++++++++++++++++++----------
 1 file changed, 34 insertions(+), 14 deletions(-)

diff --git a/include/libsemigroups/sims.hpp b/include/libsemigroups/sims.hpp
index 9bc7853bf..656fccede 100644
--- a/include/libsemigroups/sims.hpp
+++ b/include/libsemigroups/sims.hpp
@@ -116,7 +116,7 @@ namespace libsemigroups {
    public:
     //! Number of congruences found at time of last report.
     //!
-    //! This member holds the of the number of congruences found by the
+    //! This member holds the number of congruences found by the
     //! Sims1 or Sims2 algorithm at the time of the last call
     //! to \ref stats_check_point.
     //!
@@ -638,7 +638,7 @@ namespace libsemigroups {
     //! Define the length of a "long" rule.
     //!
     //! This function modifies \ref presentation so that the rules whose length
-    //! (sum of the lengths of both sizes) is at least  \p val (if any) occur at
+    //! (sum of the lengths of both sides) is at least  \p val (if any) occur at
     //! the end of `presentation().rules` and so that `cbegin_long_rules` points
     //! at the such rule.
     //!
@@ -682,9 +682,6 @@ namespace libsemigroups {
     //!
     //! \returns A reference to \c this.
     //!
-    //! \exceptions
-    //! \noexcept
-    //!
     //! \sa \ref pruners
     //!
     //! \warning When running the Sims low-index backtrack with multiple
@@ -731,7 +728,7 @@ namespace libsemigroups {
     //! represented by the relations of the presentation returned by
     //! \ref include.
     //!
-    //! \returns A const reference to `Presentation<word_type>`.
+    //! \returns A const reference to `std::vector<word_type>`.
     //!
     //! \exceptions
     //! \noexcept
@@ -848,7 +845,7 @@ namespace libsemigroups {
     //! represented by the relations of the presentation returned by
     //! \ref exclude.
     //!
-    //! \returns A const reference to `Presentation<word_type>`.
+    //! \returns A const reference to `std::vector<word_type>`.
     //!
     //! \exceptions
     //! \noexcept
@@ -919,8 +916,6 @@ namespace libsemigroups {
     //! only taken among those that do not contain the pairs of elements of the
     //! underlying semigroup (defined by the presentation returned by \ref
     //! presentation) represented by the relations returned by `exclude()`.
-    //! \brief Define a set of pairs that should be included in every
-    //! congruence.
     //!
     //! \tparam Container the type of the argument, an container of
     //! word_type objects.
@@ -985,9 +980,7 @@ namespace libsemigroups {
     //!
     //! \note This setting has no effect if \ref number_of_threads is 1.
     //!
-    //! \returns A const reference to
-    //! `std::vector<std::function<bool(word_graph_type const&)>>`, the set of
-    //! all pruners.
+    //! \returns A `size_t`.
     //!
     //! \exceptions
     //! \noexcept
@@ -1611,7 +1604,7 @@ namespace libsemigroups {
     //! the maximum number of classes in a congruence.
     //!
     //! \returns An iterator \c it of type \c iterator pointing to an WordGraph
-    //! with at most \p n nodes.
+    //! with at most \p n or \p n + 1 nodes.
     //!
     //! \throws LibsemigroupsException if \p n is \c 0.
     //! \throws LibsemigroupsException if `presentation()`
@@ -1738,6 +1731,33 @@ namespace libsemigroups {
       presentation(std::move(p));
     }
 
+    //! \brief Reinitialize an existing Sims2 object.
+    //!
+    //! This function puts an object back into the same state as if it had
+    //! been newly constructed from the presentation \p p.
+    //!
+    //! \tparam Word the type of the words in the presentation \p p .
+    //!
+    //! \param p the presentation.
+    //!
+    //! \returns A reference to \c *this.
+    //!
+    //! \throws LibsemigroupsException if `to_presentation<word_type>(p)` throws
+    //! \throws LibsemigroupsException if `p` is not valid
+    //! \throws LibsemigroupsException if `p` has 0-generators and 0-relations.
+    //!
+    //! \warning This function has no exception guarantee, the object will be
+    //! in the same state as if it was default constructed if an exception is
+    //! thrown.
+    //!
+    //! \sa presentation(Presentation<Word> const&)
+    template <typename Word>
+    Sims2& init(Presentation<Word> const& p) {
+      init();
+      presentation(p);
+      return *this;
+    }
+
 #ifdef PARSED_BY_DOXYGEN
     //! \copydoc Sims1::number_of_congruences
     uint64_t number_of_congruences(size_t n);
@@ -2753,7 +2773,7 @@ namespace libsemigroups {
     //! word graph \p wg on the free monoid.
     //!
     //! \throws LibsemigroupsException if the argument \p wg does not define a
-    //! right congruence on the semigroup or monoid presented by \p p.
+    //! right congruence on the free monoid.
     template <typename Node>
     rx::iterator_range<const_rcgp_iterator>
     right_generating_pairs(WordGraph<Node> const& wg) {