Address sjacobi's review comments.

Author: m-renaud

Data/HashSet.hs

@@ -26,40 +26,71 @@ A 'HashSet' makes no guarantees as to the order of its elements.
 the set you passed in, they create a new set. In order to keep the changes
 you need to assign it to a new variable.
 
-== Example
+== Examples
 
-@
-import qualified Data.HashSet as HashSet
+All the examples below assume @HashSet@ is imported qualified, and uses the following @dataStructures@ set.
 
--- Create an empty HashSet.
-let s = HashSet.'HashSet.empty'
+>>> import qualified Data.HashSet as HashSet
+>>> let dataStructures = HashSet.fromList ["Set", "Map", "Graph", "Sequence"]
 
--- Create a HashSet from a list of elements.
-let s1 = HashSet.'HashSet.fromList' ["a", "b"]
+=== Basic Operations
 
--- Remove an entry from the HashSet @s1@, storing the new set in @s2@.
-let s2 = HashSet.'HashSet.delete' "a" s1
+Check membership in a set:
 
--- Print the @HashSet@ @s1@, notice it still contains the deleted @"a"@.
-print s1
-> HashSet.'HashSet.fromList' ["a","b"]
+>>> -- Check if "Map" and "Trie" are in the set of data structures.
+>>> HashSet.member "Map" dataStructures
+True
+>>> HashSet.member "Trie" dataStructures
+False
 
--- Print the modified @HashSet@, notice that it does not contain the deleted @"a"@.
-print s2
-> HashSet.'HashSet.fromList' ["b"]
-@
+Add a new entry to the set:
+
+>>> let moreDataStructures = HashSet.insert "Trie" dataStructures
+>>> HashSet.member \"Trie\" moreDataStructures
+> True
+
+Remove the @\"Graph\"@ entry from the set of data structures.
+
+>>> let fewerDataStructures = HashSet.delete "Graph" dataStructures
+>>> HashSet.toList fewerDataStructures
+["Map","Set","Sequence"]
+
+
+Create a new set and combine it with our original set.
+
+>>> let unorderedDataStructures = HashSet.fromList ["HashSet", "HashMap"]
+>>> HashSet.union dataStructures unorderedDataStructures
+fromList ["Map","HashSet","Graph","HashMap","Set","Sequence"]
+
+=== Using custom data with HashSet
+
+To create a @HashSet@ of your custom type, you must derive @Eq@ and
+@Hashable@. The @Hashable@ typeclass is defined in the
+<https://hackage.haskell.org/packages/hashable hashable> package and the
+recommended way to define the instance is using generics, for which you'll need
+the @DeriveGeneric@ GHC extension.
+
+We'll start by setting up our custom data type:
+
+>>> :set -XDeriveGeneric
+>>> -- or {-# DeriveGeneric #-} if writing a Haskell source file.
+>>> import GHC.Generics (Generic)
+>>> import Data.Hashable
+>>> data Person = Person { name :: String, likesDogs :: Bool } deriving (Show, Eq, Generic)
+>>> instance Hashable Person
+
+And now we'll use it!
+
+>>> let people = HashSet.fromList [Person "Lana" True, Person "Joe" False, Person "Simon" True]
+>>> HashSet.filter likesDogs people
+fromList [Person {name = "Simon", likesDogs = True},Person {name = "Lana", likesDogs = True}]
 
-__IMPORTANT:__ @HashSet@ relies on the @element@ type having instances of the
-@Eq@ and @Hashable@ typeclasses for its internal representation. These are
-already defined for builtin types, and if you are using your own data type you
-can use the <https://en.wikibooks.org/wiki/Haskell/Classes_and_types#Deriving deriving>
-mechanism.
 
 == Performance
 
 The implementation is based on /hash array mapped trie/.  A
-'HashSet' is often faster than other tree-based set types,
-especially when value comparison is expensive, as in the case of
+'HashSet' is often faster than other 'Ord'-based set types,
+especially when value comparisons are expensive, as in the case of
 strings.
 
 Many operations have a average-case complexity of /O(log n)/.  The