Doc updates.

Author: lorentey

README.md

@@ -60,7 +60,7 @@ ordered collection types that use B-trees for their underlying storage.
     by the higher-level abstractions above (and more!).
 
     The `BTree` type is public; you may want to use it if you need a collection flavor that 
-    isn't provided by default (such as a MultiMap or a Bag), 
+    isn't provided by default (such as a multimap) 
     or if you need to use an operation that isn't exposed by the wrappers.
 
 All of these collections are structs and they implement the same copy-on-write value semantics as

Sources/SortedBag.swift

@@ -7,19 +7,22 @@
 //
 
 /// A sorted collection of comparable elements; also known as a multiset.
-/// `SortedBag` is like a `SortedSet` that allows multiple members that are equal to each other.
+/// `SortedBag` is like a `SortedSet` except it can contain multiple members that are equal to each other.
 /// Lookup, insertion and removal of any element has logarithmic complexity.
 ///
 /// `SortedBag` stores duplicate elements in their entirety; it doesn't just count multiplicities.
 /// This is an important feature when equal elements can be distinguished by identity comparison or some other means.
+/// (If you're OK with just counting duplicates, use a `Map` or a `Dictionary` with the multiplicity as the value.)
 ///
 /// `SortedBag` is a struct with copy-on-write value semantics, like Swift's standard collection types.
-/// It uses an in-memory b-tree for element storage, whose individual nodes may be shared with other ordered sets.
-/// Mutating a set whose storage is (partially or completely) shared requires copying of only O(log(`count`)) elements.
-/// (Thus, mutation of shared ordered sets may be cheaper than ordinary sets, which need to copy all elements.)
+/// It uses an in-memory b-tree for element storage, whose individual nodes may be shared with other sorted sets or bags.
+/// Mutating a bag whose storage is (partially or completely) shared requires copying of only O(log(`count`)) elements.
+/// (Thus, mutation of shared `SortedBag`s may be cheaper than ordinary `Set`s, which need to copy all elements.)
 ///
-/// Set operations on ordered sets (such as taking the union, intersection or difference) can take as little as
+/// Set operations on sorted bags (such as taking the union, intersection or difference) can take as little as
 /// O(log(n)) time if the elements in the input bags aren't too interleaved.
+///
+/// - SeeAlso: `SortedSet`
 public struct SortedBag<Element: Comparable>: SetAlgebra {
     internal typealias Tree = BTree<Element, Void>
 

Sources/SortedSet.swift

@@ -11,12 +11,14 @@
 /// Lookup, insertion and removal of any element has logarithmic complexity.
 ///
 /// `SortedSet` is a struct with copy-on-write value semantics, like Swift's standard collection types.
-/// It uses an in-memory b-tree for element storage, whose individual nodes may be shared with other ordered sets.
+/// It uses an in-memory b-tree for element storage, whose individual nodes may be shared with other sorted sets.
 /// Mutating a set whose storage is (partially or completely) shared requires copying of only O(log(`count`)) elements.
-/// (Thus, mutation of shared ordered sets may be cheaper than ordinary sets, which need to copy all elements.)
+/// (Thus, mutation of shared `SortedSet`s may be cheaper than ordinary `Set`s, which need to copy all elements.)
 ///
-/// Set operations on ordered sets (such as taking the union, intersection or difference) can take as little as
+/// Set operations on sorted sets (such as taking the union, intersection or difference) can take as little as
 /// O(log(n)) time if the elements in the input sets aren't too interleaved.
+///
+/// - SeeAlso: `SortedBag`
 public struct SortedSet<Element: Comparable>: SetAlgebra {
     internal typealias Tree = BTree<Element, Void>