Merge branch 'usage_statements'

Adding usage statements for Capture.pod and Channel.pod

lib/Type/Capture.pod

@@ -66,20 +66,38 @@ just values:
 
 =head2 method list
 
+Defined as:
+
     method list(Capture:D:) returns Positional
 
+Usage:
+
+    CAPTURE.list
+
 Returns the positional part of the Capture.
 
 =head2 method hash
 
+Defined as:
+
     method hash(Capture:D:) returns Associative
 
+Usage:
+
+    CAPTURE.hash
+
 Returns the named/hash part of the Capture.
 
 =head2 method elems
 
+Defined as:
+
     method elems(Capture:D:) returns Int:D
 
+Usage:
+
+    CAPTURE.elems
+
 Returns the number of positional elements in the Capture.
 
 =end pod

lib/Type/Channel.pod

@@ -24,15 +24,27 @@ one or more producers to one or more consumers.
 
 =head2 method send
 
+Defined as:
+
     method send(Channel:D: \item)
 
+Usage:
+
+    CHANNEL.send(ITEM)
+
 Enqueues an item into the channel. Throws an exception of type
 L<X::Channel::SendOnClosed> if the channel has been closed already.
 
 =head2 method receive
 
+Defined as:
+
     method receive(Channel:D:)
 
+Usage:
+
+   CHANNEL.receive
+
 Receives and removes an item from the channel. It blocks if no item is
 present, waiting for a C<send> from another thread.
 
@@ -49,8 +61,14 @@ See method C<poll> for a non-blocking version that won't throw exceptions.
 
 =head2 method poll
 
+Defined as:
+
     method poll(Channel:D:)
 
+Usage:
+
+    CHANNEL.poll
+
 Receives and removes an item from the channel. If no item is present, returns
 C<Nil> instead of waiting.
 
@@ -59,39 +77,70 @@ closing and failure.
 
 =head2 method close
 
+Defined as:
+
     method close(Channel:D:)
 
+Usage:
+
+    CHANNEL.close
+
 Close the channel. This makes subsequent C<send> calls die, as well as a
 C<receive> call past the end of the queue,
 and is a prerequisite for C<list> to terminate.
 
 =head2 method list
 
+Defined as:
+
     method list(Channel:D:) returns List:D
 
+Usage:
+
+    CHANNEL.list
+
 Returns a list of all remaining items in the queue, and removes them from the
 channel. This can only terminate once C<close> has been called.
 
 =head2 method closed
 
+Defined as:
+
     method closed(Channel:D:) returns Promise:D
 
+Usage:
+
+    CHANNEL.closed
+
 Returns a promise that will be kept once the channel is closed by a call to
 method C<close>.
 
 =head2 method fail
 
+Defined as:
+
     method fail(Channel:D: $error)
 
+Usage:
+
+    CHANNEL.fail
+
 Closes the channel (that is, makes subsequent C<send> calls die), and enqueues
 the error as the final element in the channel. Method C<receive> will throw
 the error as an exception.
 
 =head2 sub await
 
+Defined as:
+
     multi sub await(Channel:D)
     multi sub await(*@)
 
+Usage:
+
+    await(CHANNEL)
+    await(CHANNELS)
+
 Waits until all of one or more channels has a value available, and returns
 those values (it calls C<.receive> on the channel). Also works with
 L<promises|/type/Promise>.