Merge pull request #2655 from Kaiepi/supply2

Document the :&tap parameter of Supply.tap

Author: Altai-man

doc/Type/Supply.pod6

@@ -53,6 +53,7 @@ Further examples can be found in the L<concurrency page|/language/concurrency#Su
 method tap(Supply:D: &emit = -> $ { },
         :&done,
         :&quit,
+        :&tap
     --> Tap:D)
 
 Creates a new tap (a kind of subscription if you will), in addition to all
@@ -69,7 +70,14 @@ block will then reach its end).
 The C<&quit> callback is called if the tap is on a supply block which exits with an error. It is also
 called if the C<quit> method is invoked on the parent C<Supplier> (in the case of a supply block any
 one C<Supplier> quitting with an uncaught exception will call the C<&quit> callback as the block will
-exit with an error).
+exit with an error). The error is passed as a parameter to the callback.
+
+The C<&tap> callback is called once the L<Tap|/type/Tap> object is created,
+which is passed as a parameter to the callback. The callback is called ahead of
+C<emit>/C<done>/C<quit>, providing a reliable way to get the C<Tap> object. One
+case where this is useful is when the C<Supply> begins emitting values
+synchronously, since the call to C<.tap> won't return the C<Tap> object until
+it is done emitting, preventing it from being stopped if needed.
 
 Method C<tap> returns an object of type L<Tap|/type/Tap>, on which you can
 call the C<close> method to cancel the subscription.