Auto merge of #39708 - jethrogb:patch-4, r=frewsxcv

Update set operations documentation

Reminding people of set terminology.

2 files changed, 30 insertions, 14 deletions

diff --git a/src/libcollections/btree/set.rs b/src/libcollections/btree/set.rs
index bfffa0b8efa..e3c990c80de 100644
--- a/src/libcollections/btree/set.rs
+++ b/src/libcollections/btree/set.rs
@@ -289,7 +289,9 @@ impl<T: Ord> BTreeSet<T> {
 }
 
 impl<T: Ord> BTreeSet<T> {
-    /// Visits the values representing the difference, in ascending order.
+    /// Visits the values representing the difference,
+    /// i.e. the values that are in `self` but not in `other`,
+    /// in ascending order.
     ///
     /// # Examples
     ///
@@ -315,7 +317,9 @@ impl<T: Ord> BTreeSet<T> {
         }
     }
 
-    /// Visits the values representing the symmetric difference, in ascending order.
+    /// Visits the values representing the symmetric difference,
+    /// i.e. the values that are in `self` or in `other` but not in both,
+    /// in ascending order.
     ///
     /// # Examples
     ///
@@ -343,7 +347,9 @@ impl<T: Ord> BTreeSet<T> {
         }
     }
 
-    /// Visits the values representing the intersection, in ascending order.
+    /// Visits the values representing the intersection,
+    /// i.e. the values that are both in `self` and `other`,
+    /// in ascending order.
     ///
     /// # Examples
     ///
@@ -369,7 +375,9 @@ impl<T: Ord> BTreeSet<T> {
         }
     }
 
-    /// Visits the values representing the union, in ascending order.
+    /// Visits the values representing the union,
+    /// i.e. all the values in `self` or `other`, without duplicates,
+    /// in ascending order.
     ///
     /// # Examples
     ///
@@ -480,7 +488,7 @@ impl<T: Ord> BTreeSet<T> {
         Recover::get(&self.map, value)
     }
 
-    /// Returns `true` if the set has no elements in common with `other`.
+    /// Returns `true` if `self` has no elements in common with `other`.
     /// This is equivalent to checking for an empty intersection.
     ///
     /// # Examples
@@ -502,7 +510,8 @@ impl<T: Ord> BTreeSet<T> {
         self.intersection(other).next().is_none()
     }
 
-    /// Returns `true` if the set is a subset of another.
+    /// Returns `true` if the set is a subset of another,
+    /// i.e. `other` contains at least all the values in `self`.
     ///
     /// # Examples
     ///
@@ -544,7 +553,8 @@ impl<T: Ord> BTreeSet<T> {
         true
     }
 
-    /// Returns `true` if the set is a superset of another.
+    /// Returns `true` if the set is a superset of another,
+    /// i.e. `self` contains at least all the values in `other`.
     ///
     /// # Examples
     ///
diff --git a/src/libstd/collections/hash/set.rs b/src/libstd/collections/hash/set.rs
index a3f7e13bbf9..d438aa8b3ac 100644
--- a/src/libstd/collections/hash/set.rs
+++ b/src/libstd/collections/hash/set.rs
@@ -291,7 +291,8 @@ impl<T, S> HashSet<T, S>
         Iter { iter: self.map.keys() }
     }
 
-    /// Visit the values representing the difference.
+    /// Visit the values representing the difference,
+    /// i.e. the values that are in `self` but not in `other`.
     ///
     /// # Examples
     ///
@@ -321,7 +322,8 @@ impl<T, S> HashSet<T, S>
         }
     }
 
-    /// Visit the values representing the symmetric difference.
+    /// Visit the values representing the symmetric difference,
+    /// i.e. the values that are in `self` or in `other` but not in both.
     ///
     /// # Examples
     ///
@@ -348,7 +350,8 @@ impl<T, S> HashSet<T, S>
         SymmetricDifference { iter: self.difference(other).chain(other.difference(self)) }
     }
 
-    /// Visit the values representing the intersection.
+    /// Visit the values representing the intersection,
+    /// i.e. the values that are both in `self` and `other`.
     ///
     /// # Examples
     ///
@@ -373,7 +376,8 @@ impl<T, S> HashSet<T, S>
         }
     }
 
-    /// Visit the values representing the union.
+    /// Visit the values representing the union,
+    /// i.e. all the values in `self` or `other`, without duplicates.
     ///
     /// # Examples
     ///
@@ -489,7 +493,7 @@ impl<T, S> HashSet<T, S>
         Recover::get(&self.map, value)
     }
 
-    /// Returns `true` if the set has no elements in common with `other`.
+    /// Returns `true` if `self` has no elements in common with `other`.
     /// This is equivalent to checking for an empty intersection.
     ///
     /// # Examples
@@ -511,7 +515,8 @@ impl<T, S> HashSet<T, S>
         self.iter().all(|v| !other.contains(v))
     }
 
-    /// Returns `true` if the set is a subset of another.
+    /// Returns `true` if the set is a subset of another,
+    /// i.e. `other` contains at least all the values in `self`.
     ///
     /// # Examples
     ///
@@ -532,7 +537,8 @@ impl<T, S> HashSet<T, S>
         self.iter().all(|v| other.contains(v))
     }
 
-    /// Returns `true` if the set is a superset of another.
+    /// Returns `true` if the set is a superset of another,
+    /// i.e. `self` contains at least all the values in `other`.
     ///
     /// # Examples
     ///