[2836] Update the docs about trees

src/lib/datasrc/memory/domaintree.h

@@ -1301,21 +1301,24 @@ public:
     /// doesn't exist.
     ///
     /// This method normally involves resource allocation.  If it fails
-    /// the corresponding standard exception will be thrown.
+    /// \c std::bad_alloc will be thrown.  Also, depending on details the
+    /// specific \c MemorySegment, it can propagate the \c MemorySegmentGrown
+    /// exception.
     ///
     /// This method does not provide the strong exception guarantee in its
-    /// strict sense; if an exception is thrown in the middle of this
+    /// strict sense; there can be new empty nodes that are superdomains of
-    /// method, the internal structure may change.  However, it should
+    /// the domain to be inserted as a side effect.  However, the tree
-    /// still retain the same property as a mapping container before this
+    /// retains internal integrity otherwise, and, in particular, the intended
-    /// method is called.  For example, the result of \c find() should be
+    /// insert operation is "resumable": if the \c insert() method is called
-    /// the same.  This method provides the weak exception guarantee in its
+    /// again with the same argument after resolving the cause of the
-    /// normal sense.
+    /// exception (possibly multiple times), it should now succeed.  Note,
-    ///
+    /// however, that i case of \c MemorySegmentGrown the address of the
-    /// In particular, this method can propagate the \c MemorySegmentGrown
+    /// `DomainTree` object may have been reallocated if it was created with
-    /// exception from the \c MemorySegment object. In such case, some of
+    /// the same \c MemorySegment (which will often be the case in practice).
-    /// the internal nodes may have been already allocated (but hold no data).
+    /// So the caller may have to re-get the address before calling \c insert
-    /// Retrying the insert (possibly multiple times) would lead to the same
+    /// again.  It can be done using the concept of "named addresses" of
-    /// structure eventually.
+    /// \c MemorySegment, or the direct caller may not have to worry about it
+    /// if this condition is guaranteed at a higher level.
     ///
     /// \param mem_sgmt A \c MemorySegment object for allocating memory of
     /// a new node to be inserted.  Must be the same segment as that used