Add the add and remove BagHash methods

This commit adds method documentation for the `add` and `remove`
methods on the `BagHash` class and adds narrative documentation and
examples showing their use.  It also adds "baghash's" to the
spellcheck dictionary to prevent a test failure.

Author: codesections

doc/Type/BagHash.pod6

@@ -33,10 +33,9 @@ or the
 L«C< < > > postcircumfix operator|/language/operators#postcircumfix_<_>»
 for literal string keys, which
 returns the corresponding integer weight for keys that are
-elements of the bag, and C<0> for keys that aren't.  They can also be used to
-modify weights; setting a weight to C<0> automatically removes that element from
-the bag, and setting a weight to a positive number adds that element if it
-didn't already exist:
+
+elements of the bag, and C<0> for keys that aren't.  These operators can also be
+used to modify weights (see L<Updating BagHash Objects|#Updating_BagHash_Objects>, below).
 
 =begin code
 my $breakfast = <spam eggs spam spam bacon spam>.BagHash;
@@ -103,6 +102,40 @@ or using the masquerading syntax:
     my %bh is BagHash[Int] = <a b b c c c>;
     # Type check failed in binding; expected Int but got Str ("a")
 
+=head1 Updating BagHash Objects
+
+Once you have created a C<BagHash>, you can update its values in two
+ways.  First, you can use the C<add> and C<remove> methods:
+
+    my $n = BagHash.new: "a", "b", "c", "c";
+    say $n.raku;             # OUTPUT: «("b"=>1,"a"=>1,"c"=>2).BagHash␤»
+    $n.add('c');
+    say $n.raku;             # OUTPUT: «("b"=>1,"c"=>3,"a"=>1).BagHash␤»
+    $n.remove(('b', 'a'),);
+    say $n.raku;             # OUTPUT: «("c"=>3).BagHash␤»
+    $n.remove('c');
+    say $n.raku;             # OUTPUT: «("c"=>2).BagHash␤»
+
+Note that, as shown in the final example, the C<remove> method removes
+a I<single> value from the C<BagHash>; it doesn't entirely remove the
+key from the C<BagHash>.
+
+Alternatively, you can use assignment (including with L<autoincrement
+operators|/language/operators#Autoincrement_precedence> such as C<++>
+and C<-->) to modify the C<BagHash>'s contents.
+
+    my $n = BagHash.new: "a", "b", "c", "c";
+    say $n.raku;             # OUTPUT: «("b"=>1,"a"=>1,"c"=>2).BagHash␤»
+    $n<c>++;
+    say $n.raku;             # OUTPUT: «("b"=>1,"c"=>3,"a"=>1).BagHash␤»
+    $n<b> -= 1;
+    say $n.raku;             # OUTPUT: «("a"=>1,"c"=>3).BagHash␤»
+    $n{'a'} = 0;
+    say $n.raku;             # OUTPUT: «("c"=>3).BagHash␤»
+
+Using either syntax, if you set the value of an item to zero or less
+than zero, the item will be removed from the C<BagHash>.
+
 =head1 Operators
 
 See L<Operators with set
@@ -143,6 +176,32 @@ say $a.sort;  # OUTPUT: «(2 => 2 3 => 1 4 => 1 18 => 1)␤»
 say $a.sort.reverse;  # OUTPUT: «(18 => 1 4 => 1 3 => 1 2 => 2)␤»
 =end code
 
+=head2 method add
+
+    method add(BagHash: \to-add, *%_ --> Nil)
+
+When given single item, C<add> adds it to the C<BagHash> or, if it was
+already present, increases its weight by 1.  When given a C<List>,
+C<Array>, C<Seq>, or any other type that C<does> the
+L<C«Iterator»|/type/Iterator> Role, C<add> adds each element of the
+C<Iterator> to the C<SetHash> or increments the weight of each element
+by 1.
+
+I<Note:> since version 2020.02.
+
+=head2 method remove
+
+    method remove(BagHash: \to-remove, *%_ --> Nil)
+
+When given single item, C<remove> reduces the weight of that item by
+one.  If this results in the item having a weight of 0, this removes
+the item from the C<BagHash>.  If the item is not present in the
+C<BagHash>, C<remove> has no effect.  When given a C<List>, C<Array>,
+C<Seq>, or any other type that C<does> the
+L<C«Iterator»|/type/Iterator> Role, C<remove> reduces the weight of
+each element by 1 and removes any items with the resulting weight of 0.
+
+I<Note:> since version 2020.02.
 
 =head1 See Also
 

xt/pws/words.pws

@@ -125,6 +125,7 @@ backtrace
 backtraces
 baggy's
 baghash
+baghash's
 baghashes
 baldr
 barewords