From b9b607813705eb4cf3396a2c4abb23befb74ce6a Mon Sep 17 00:00:00 2001
From: David Cosgrove <davidacosgroveaz@gmail.com>
Date: Sat, 1 Nov 2025 05:18:08 +0000
Subject: [PATCH] Extra explanation of getPosition() and getReagents(). (#8909)

---
 .../ChemReactions/Enumerate/Enumerate.h       |  3 ++-
 .../ChemReactions/Enumerate/EnumerateBase.h   |  4 +++-
 .../GraphMol/ChemReactions/Wrap/Enumerate.cpp | 23 +++++++++++++------
 3 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/Code/GraphMol/ChemReactions/Enumerate/Enumerate.h b/Code/GraphMol/ChemReactions/Enumerate/Enumerate.h
index 9b4e1f6cb..28b0aab3b 100644
--- a/Code/GraphMol/ChemReactions/Enumerate/Enumerate.h
+++ b/Code/GraphMol/ChemReactions/Enumerate/Enumerate.h
@@ -127,7 +127,8 @@ class RDKIT_CHEMREACTIONS_EXPORT EnumerateLibrary
                    const EnumerationParams &params = EnumerationParams());
   EnumerateLibrary(const EnumerateLibrary &rhs);
 
-  //! Return the reagents used in the library
+  //! Return the reagents used in the library.  This may be fewer reagents than
+  // the input as it is only those compatible with the reaction.
   const EnumerationTypes::BBS &getReagents() const { return m_bbs; }
 
   //! Get the next product set
diff --git a/Code/GraphMol/ChemReactions/Enumerate/EnumerateBase.h b/Code/GraphMol/ChemReactions/Enumerate/EnumerateBase.h
index 962cfa6ed..f0295fc16 100644
--- a/Code/GraphMol/ChemReactions/Enumerate/EnumerateBase.h
+++ b/Code/GraphMol/ChemReactions/Enumerate/EnumerateBase.h
@@ -122,7 +122,9 @@ class RDKIT_CHEMREACTIONS_EXPORT EnumerateLibraryBase {
   /// Each result vector corresponds for a product template.
   virtual std::vector<std::vector<std::string>> nextSmiles();
 
-  //! Get the current position into the reagent vectors
+  //! Get the current position into the reagent vectors as returned by
+  ///  getReagents.  It is not necessarily the index into the input reagents
+  ///  as it is only for the reagents compatible with the reaction.
   ///  Use getState/setState to save/restart the enumeration
   ///  from this position.
   const EnumerationTypes::RGROUPS &getPosition() const;
diff --git a/Code/GraphMol/ChemReactions/Wrap/Enumerate.cpp b/Code/GraphMol/ChemReactions/Wrap/Enumerate.cpp
index abaec63f3..5620c6c54 100644
--- a/Code/GraphMol/ChemReactions/Wrap/Enumerate.cpp
+++ b/Code/GraphMol/ChemReactions/Wrap/Enumerate.cpp
@@ -170,7 +170,10 @@ struct enumeration_wrapper {
              "Inititialize the library from a binary string")
         .def(
             "GetPosition", &RDKit::EnumerateLibraryBase::getPosition,
-            "Returns the current enumeration position into the reagent vectors",
+            "Returns the current enumeration position into the reagent vectors, as"
+            " returned by GetReagents().  They do not necessarily refer to"
+            " the input reagent sets as they only refer to reagents compatible"
+            " with the reaction.",
             python::return_internal_reference<
                 1, python::with_custodian_and_ward_postcall<0, 1>>(),
             python::args("self"))
@@ -308,11 +311,14 @@ for result in itertools.islice(libary2, 1000):\n\
                           python::optional<const RDKit::EnumerationParams &>>(
             python::args("self", "rxn", "reagents", "enumerator", "params")))
 
-        .def("GetReagents", &RDKit::EnumerateLibrary::getReagents,
-             "Return the reagents used in this library.",
-             python::return_internal_reference<
-                 1, python::with_custodian_and_ward_postcall<0, 1>>(),
-             python::args("self"));
+        .def(
+            "GetReagents", &RDKit::EnumerateLibrary::getReagents,
+            "Return the reagents used in this library.  These are the subset"
+            " of the input reagents that are compatible with the reaction so may"
+            " be smaller than the input reagent sets.",
+            python::return_internal_reference<
+                1, python::with_custodian_and_ward_postcall<0, 1>>(),
+            python::args("self"));
 
     // iterator_wrappers<EnumerateLibrary>().wrap("EnumerateLibraryIterator");
 
@@ -342,7 +348,10 @@ for result in itertools.islice(libary2, 1000):\n\
              "strategy.\n"
              "Note that some strategies are effectively infinite.")
         .def("GetPosition", &EnumerationStrategyBase::getPosition,
-             "Return the current indices into the arrays of reagents",
+             "Return the current indices into the arrays of reagents, as"
+             " returned by GetReagents().  They do not necessarily refer to"
+             " the input reagent sets as they only refer to reagents compatible"
+             " with the reaction.",
              python::return_internal_reference<
                  1, python::with_custodian_and_ward_postcall<0, 1>>(),
              python::args("self"))