Added usage statements to Types Iterable.pod through Lock.pod

Author: dha

lib/Type/Iterable.pod

@@ -19,6 +19,8 @@ Its important aspect is a method stub for C<iterator>.
 
 =head2 method iterator
 
+Defined as:
+
     method iterator() returns Iterator:D { ... }
 
 Method stub that ensures all classes doing the C<Iteraable> role have a method
@@ -28,8 +30,14 @@ It is supposed to return an L<Iterator|/type/Iterator>.
 
 =head2 method flat
 
+Defined as:
+
     method flat() return Iterable
 
+Usage:
+
+    ITERABLE.flat
+
 Returns another L<Iterable> that flattens out all iterables that the first one
 returns.
 
@@ -48,25 +56,43 @@ returns C<("a", "b", "c", "d")>, but it does not flatten itemized sublists:
 
 =head2 method lazy
 
+Defined as:
+
     method lazy() returns Iterable
 
+Usage:
+
+    ITERABLE.lazy
+
 Returns a lazy iterable wrapping the invocant.
 
 =head2 method hyper
 
+Defined as:
+
     method hyper(Int(Cool) :$batch = 64, Int(Cool) :$degree = 4)
                 returns Iterable
 
+Usage:
+
+    ITERABLE.hyper(BATCH?, DEGREE?)
+
 Returns another Iterable that is potentially iterated in parallel, with a
 given batch size and degree of parallelism.
 
 The order of elements are preserved.
 
 =head2 method race
 
+Defined as:
+
     method race(Int(Cool) :$batch = 64, Int(Cool) :$degree = 4)
                 returns Iterable
 
+Usage:
+
+    ITERABLE.race(BATCH?, DEGREE?)
+
 Returns another Iterable that is potentially iterated in parallel, with a
 given batch size and degree of parallelism.
 

lib/Type/Iterator.pod

@@ -29,8 +29,14 @@ iterator API. Any other behavior is undefined and implementation dependent.
 
 =head2 method pull-one
 
+Defined as:
+
     method pull-one(Iterator:D:) returns Mu { ... }
 
+Usage:
+
+    ITERATOR.pull-one
+
 This method stub ensures that classes implementing the C<Iterator> role
 provide a method named C<pull-one>.
 
@@ -39,8 +45,14 @@ the sentenial value C<IterationEnd> if no more elements are available.
 
 =head2 method push-exactly
 
+Defined as:
+
     method push-exactly(Iterator:D: $target, int $count) returns Mu
 
+Usage:
+
+    ITERATOR.push-exactly(TARGET, COUNT)
+
 Produces C<$count> elements, and for each of them, calls
 C<$target.push($value)>.
 
@@ -50,8 +62,14 @@ C<$count>.
 
 =head2 method push-at-least
 
+Defined as:
+
     method push-at-least(Iterator:D: $target, int $count) returns Mu
 
+Usage:
+
+    ITERATOR.push-at-least(TARGET, COUNT)
+
 Produces at least C<$count> elements, and for each of them, calls
 C<$target.push($value)>.
 
@@ -65,17 +83,29 @@ produce more elements to achieve better performance.
 
 =head2 method push-all
 
+Defined as:
+
     method push-all(Iterator:D: $target)
 
+Usage:
+
+    ITERATOR.push-all(TARGET)
+
 Produces all elements from the iterator and pushes them to C<$target>.
 
 The fallback is implemented in terms of repeated C<push-at-least> with a large
 C<$count>.
 
 =head2 method push-until-lazy
 
+Defined as:
+
     method push-until-lazy(Iterator:D: $target) returns Mu
 
+Usage:
+
+    ITERATOR.push-until-lazy(TARGET)
+
 Produces values until it considers itself to be lazy, and pushes them onto
 C<$target>.
 
@@ -84,8 +114,14 @@ which might be lazy, while others aren't.
 
 =head2 method is-lazy
 
+Defined as:
+
     method is-lazy(Iterator:D:) returns Bool:D
 
+Usage:
+
+    ITERATOR.is-lazy
+
 Returns C<True> for iterators that consider themselves lazy, and C<False>
 otherwise.
 
@@ -94,16 +130,28 @@ return C<True> here, for example C<(1..6).roll(*)>.
 
 =head2 method count-only
 
+Defined as:
+
     method count-only(Iterator:D:) returns int
 
+Usage:
+
+    ITERATOR.count-only
+
 Produces and discards all elements until it returns the end of the iteration,
 and returns the number of elements produced. This is useful to reduce memory
 usage in scenarios such as C<open($file).lines.elems>.
 
 =head2 method sink-all
 
+Defined as:
+
     method sink-all(Iterator:D:)
 
+Usage:
+
+    ITERATOR.sink-all
+
 Exhausts the iterator (while discarding generated elements) purely for the
 side effects of the iteraton.
 

lib/Type/Label.pod

@@ -25,14 +25,26 @@ Those label are objects of type C<Label>.
 
 =head2 method next
 
+Defined as:
+
     method next(Label:)
 
+Usage:
+
+    next LABEL
+
 Begin the next iteration of the loop associated with the label.
 
 =head2 method last
 
+Defined as:
+
     method last(Label:)
 
+Usage:
+
+    last LABEL
+
 Terminate the execution of the loop associated with the label.
 
 =end pod