Document the set and unset SetHash methods (#3583)

Add method-level documentation and overview examples using the set and
unset methods on HashSet.

Author: codesections

doc/Type/SetHash.pod6

@@ -20,22 +20,53 @@ say $fruits.elems;      # OUTPUT: «3␤»
 say $fruits.keys.sort;  # OUTPUT: «apple orange peach␤»
 =end code
 
-C<SetHash>es can be treated as object hashes using the C<{ }> postcircumfix
-operator, which returns the value C<True> for keys that are elements of the set,
-and C<False> for keys that aren't. Assigning a value that boolifies to C<True>
-or C<False>, respectively, can be used to add or remove a set element:
+Just like C<Set>s, C<SetHash>es can be treated as object hashes using the C<{ }>
+postcircumfix operator, which returns the value C<True> for keys that are
+elements of the set, and C<False> for keys that aren't.
 
 =begin code
 my $fruits = <peach apple orange apple apple>.SetHash;
 
 say $fruits<apple>;     # OUTPUT: «True␤»
 say $fruits<kiwi>;      # OUTPUT: «False␤»
+=end code
+
+Unlike C<Set>s, C<SetHash>es are mutable.  You can add an item or list of items
+to the C<SetHash> with the C<set> method and can remove an item or list of items
+with the C<unset> method:
+
+=begin code
+my $fruits = <peach>.SetHash;
+$fruits.set('apple');
+say $fruits;            # OUTPUT: «SetHash(apple peach)␤»
+
+$fruits.unset('peach');
+say $fruits;            # OUTPUT: «SetHash(apple)␤»
+
+$fruits.set(<kiwi banana apple>);
+say $fruits;            # OUTPUT: «SetHash(apple banana kiwi)␤»
+
+$fruits.unset(<apple banana kiwi>);
+say $fruits;            # OUTPUT: «SetHash()␤»
+=end code
+
+Be careful not to confuse the C<set> method, which adds an item to a C<SetHash>
+with the C<Set> method, which converts the mutable C<SetHash> into an immutable
+C<Set>.
+
+As an alternative to using the C<set> and C<unset> methods, you can also add or
+remove set elements by assigning a value that boolifies to C<True> or C<False>,
+respectively:
+
+=begin code
+my $fruits = <peach apple orange>.SetHash;
 
 $fruits<apple kiwi> = False, True;
 say $fruits.keys.sort;  # OUTPUT: «kiwi orange peach␤»
 =end code
 
-Here is a convenient shorthand idiom for adding and removing SetHash elements:
+Here is a convenient shorthand idiom for adding and removing SetHash elements
+using assignment:
 
 =begin code
 my SetHash $fruits .= new;
@@ -133,6 +164,35 @@ say $a ⊖ $b;  # OUTPUT: «SetHash(1 3 4)␤»
 say $a ∪ $b;  # OUTPUT: «SetHash(1 2 3 4)␤»
 =end code
 
+=head1 Methods
+
+=head2 method set
+
+Defined as:
+
+    method set(SetHash:D: \to-set --> Nil)
+
+When given single key, C<set> adds it to the C<SetHash>.  When given a
+C<List>, C<Array>, C<Seq>, or any other type that C<does> the
+L<C«Iterator»|/type/Iterator> Role, C<set> adds each element of the
+C<Iterator> as key to the C<SetHash>.
+
+I<Note:> since version 2020.02.
+
+=head2 method unset
+
+Defined as:
+
+    method unset(SetHash:D: \to-unset --> Nil)
+
+When given single key, C<set> removes it from the C<SetHash>.  When
+given a C<List>, C<Array>, C<Seq>, or any other type that C<does> the
+L<C«Iterator»|/type/Iterator> Role, C<set> removes each element of the
+C<Iterator> from the C<SetHash> (if it was present as a key).
+
+I<Note:> since version 2020.02.
+
+
 =head1 See Also
 
 L<Sets, Bags, and Mixes|/language/setbagmix>