Improve documentation for pool iteration function. (#17921)

There are constraints on what mutations can be done while iterating
that were not documented.

src/lib/support/Pool.h

@@ -240,8 +240,15 @@ class BitMapObjectPool : public internal::StaticAllocatorBitmap, public internal
      * @brief
      *   Run a functor for each active object in the pool
      *
-     *  @param     function The functor of type `Loop (*)(T*)`, return Loop::Break to break the iteration
-     *  @return    Loop     Returns Break or Finish according to the iteration
+     *  @param     function A functor of type `Loop (*)(T*)`.
+     *                      Return Loop::Break to break the iteration.
+     *                      The only modification the functor is allowed to make
+     *                      to the pool before returning is releasing the
+     *                      object that was passed to the functor.  Any other
+     *                      desired changes need to be made after iteration
+     *                      completes.
+     *  @return    Loop     Returns Break if some call to the functor returned
+     *                      Break.  Otherwise returns Finish.
      *
      * caution
      *   this function is not thread-safe, make sure all usage of the
@@ -365,8 +372,15 @@ class HeapObjectPool : public internal::Statistics, public internal::PoolCommon<
      * @brief
      *   Run a functor for each active object in the pool
      *
-     *  @param     function The functor of type `Loop (*)(T*)`, return Loop::Break to break the iteration
-     *  @return    Loop     Returns Break or Finish according to the iteration
+     *  @param     function A functor of type `Loop (*)(T*)`.
+     *                      Return Loop::Break to break the iteration.
+     *                      The only modification the functor is allowed to make
+     *                      to the pool before returning is releasing the
+     *                      object that was passed to the functor.  Any other
+     *                      desired changes need to be made after iteration
+     *                      completes.
+     *  @return    Loop     Returns Break if some call to the functor returned
+     *                      Break.  Otherwise returns Finish.
      */
     template <typename Function>
     Loop ForEachActiveObject(Function && function)