Document union_find_replacet

In particular, the documentation for make_union was outdated.

Author: romainbrenguier

src/util/union_find_replace.cpp

@@ -8,13 +8,13 @@ Author: Romain Brenguier, romain.brenguier@diffblue.com
 
 #include "union_find_replace.h"
 
-/// Keeps a map of symbols to expressions, such as none of the mapped values
-/// exist as a key
-/// \param a: an expression of type char array
-/// \param b: an expression to map it to, which should be either a symbol
-///             a string_exprt, an array_exprt, an array_of_exprt or an
-///             if_exprt with branches of the previous kind
-/// \return the new mapped value
+/// Merge the set containing `a` and the set containing `b`.
+/// It is guaranteed that if `b` never appears as the first argument of a
+/// `make_union` call, then it is the representative element of the set it
+/// belongs to.
+/// \param a: an expression
+/// \param b: an expression
+/// \return current representative element of the set containing `a` and `b`
 exprt union_find_replacet::make_union(const exprt &a, const exprt &b)
 {
   const exprt &lhs_root = find(a);
@@ -24,8 +24,8 @@ exprt union_find_replacet::make_union(const exprt &a, const exprt &b)
   return rhs_root;
 }
 
-/// Replace subexpressions of `expr` by a canonical element of the set they
-/// belong to.
+/// Replace subexpressions of `expr` by the representative element of the set
+/// they belong to.
 /// \param expr: an expression, modified in place
 /// \return true if expr is left unchanged
 bool union_find_replacet::replace_expr(exprt &expr) const
@@ -37,15 +37,14 @@ bool union_find_replacet::replace_expr(exprt &expr) const
 }
 
 /// \param expr: an expression
-/// \return canonical representation for expressions which belong to the same
-///         set
+/// \return representative element of the set `expr` belongs to
 exprt union_find_replacet::find(exprt expr) const
 {
   replace_expr(expr);
   return expr;
 }
 
-/// \return pairs of expression composed of expressions and a canonical
+/// \return pairs of expression composed of expressions and a representative
 ///         expression for the set they below to.
 std::vector<std::pair<exprt, exprt>> union_find_replacet::to_vector() const
 {