[Doc] Note requirement to call modifySpecies and modifyReaction

Modifying Reaction and Species objects alone does not affect Kinetics or
ThermoPhase objects unless the modified objects are passed back to
modifyReaction or modifySpecies.

include/cantera/kinetics/Kinetics.h

@@ -724,10 +724,12 @@ public:
     virtual void modifyReaction(size_t i, shared_ptr<Reaction> rNew);
 
     /**
-     * Return the Reaction object for reaction *i*.
+     * Return the Reaction object for reaction *i*. Changes to this object do
+     * not affect the Kinetics object until the #modifyReaction function is
+     * called.
      */
     shared_ptr<Reaction> reaction(size_t i);
-    
+
     shared_ptr<const Reaction> reaction(size_t i) const;
 
     //! Determine behavior when adding a new reaction that contains species not

include/cantera/thermo/Phase.h

@@ -713,10 +713,14 @@ public:
      */
     virtual void modifySpecies(size_t k, shared_ptr<Species> spec);
 
-    //! Return the Species object for the named species.
+    //! Return the Species object for the named species. Changes to this object
+    //! do not affect the ThermoPhase object until the #modifySpecies function
+    //! is called.
     shared_ptr<Species> species(const std::string& name) const;
 
-    //! Return the Species object for species whose index is *k*.
+    //! Return the Species object for species whose index is *k*. Changes to
+    //! this object do not affect the ThermoPhase object until the
+    //! #modifySpecies function is called.
     shared_ptr<Species> species(size_t k) const;
 
     //! Set behavior when adding a species containing undefined elements to just

interfaces/cython/cantera/kinetics.pyx

@@ -79,13 +79,16 @@ cdef class Kinetics(_SolutionBase):
     def reaction(self, int i_reaction):
         """
         Return a `Reaction` object representing the reaction with index
-        ``i_reaction``.
+        ``i_reaction``. Changes to this object do not affect the `Kinetics` or
+        `Solution` object until the `modify_reaction` function is called.
         """
         return wrapReaction(self.kinetics.reaction(i_reaction))
 
     def reactions(self):
         """
-        Return a list of all `Reaction` objects
+        Return a list of all `Reaction` objects. Changes to these objects do not
+        affect the `Kinetics` or `Solution` object until the `modify_reaction`
+        function is called.
         """
         return [self.reaction(i) for i in range(self.n_reactions)]
 

interfaces/cython/cantera/thermo.pyx

@@ -435,7 +435,9 @@ cdef class ThermoPhase(_SolutionBase):
         """
         Return the `Species` object for species *k*, where *k* is either the
         species index or the species name. If *k* is not specified, a list of
-        all species objects is returned.
+        all species objects is returned. Changes to this object do not affect
+        the `ThermoPhase` or `Solution` object until the `modify_species`
+        function is called.
         """
         if k is None:
             return [self.species(i) for i in range(self.n_species)]