generators.rb in xi-lang-0.1.4

- old
+ new

@@ -49,16 +49,21 @@
               i *= grow
             end
           end
         end
 
-        # Choose items from the list randomly
+        # Choose items from the +list+ randomly, +repeats+ number of times
         #
+        # +list+ can be a *finite* enumerable or Pattern.
+        #
+        # @see Pattern::Transforms#rand
+        #
         # @example
-        #   peek [1, 2, 3].p.rand             #=> [2]
-        #   peek [1, 2, 3, 4].p.rand(6)       #=> [1, 3, 2, 2, 4, 3]
+        #   peek P.rand([1, 2, 3])          #=> [2]
+        #   peek P.rand([1, 2, 3, 4], 6)    #=> [1, 3, 2, 2, 4, 3]
         #
+        # @param list [#each] list of values
         # @param repeats [Fixnum, Symbol] number or inf (default: 1)
         # @return [Pattern]
         #
         def rand(list, repeats=1)
           Pattern.new(size: repeats) do |y|
@@ -68,14 +73,19 @@
         end
 
         # Choose randomly, but only allow repeating the same item after yielding
         # all items from the list.
         #
+        # +list+ can be a *finite* enumerable or Pattern.
+        #
+        # @see Pattern::Transforms#xrand
+        #
         # @example
-        #   peek [1, 2, 3, 4, 5].p.xrand    #=> [4]
-        #   peek [1, 2, 3].p.xrand(8)       #=> [1, 3, 2, 3, 1, 2, 3, 2]
+        #   peek P.xrand([1, 2, 3, 4, 5])    #=> [4]
+        #   peek P.xrand([1, 2, 3], 8)       #=> [1, 3, 2, 3, 1, 2, 3, 2]
         #
+        # @param list [#each] list of values
         # @param repeats [Fixnum, Symbol] number or inf (default: 1)
         # @return [Pattern]
         #
         def xrand(list, repeats=1)
           Pattern.new(size: repeats) do |y|
@@ -89,14 +99,19 @@
         end
 
         # Shuffle the list in random order, and use the same random order
         # +repeats+ times
         #
+        # +list+ can be a *finite* enumerable or Pattern.
+        #
+        # @see Pattern::Transforms#shuf
+        #
         # @example
-        #   peek [1, 2, 3, 4, 5].p.xrand    #=> [4]
-        #   peek [1, 2, 3].p.xrand(8)       #=> [1, 3, 2, 3, 1, 2, 3, 2]
+        #   peek P.shuf([1, 2, 3, 4, 5])    #=> [5, 3, 4, 1, 2]
+        #   peek P.shuf([1, 2, 3], 3)       #=> [2, 3, 1, 2, 3, 1, 2, 3, 1]
         #
+        # @param list [#each] list of values
         # @param repeats [Fixnum, Symbol] number or inf (default: 1)
         # @return [Pattern]
         #
         def shuf(list, repeats=1)
           Pattern.new(size: list.size * repeats) do |y|
@@ -105,19 +120,52 @@
               xs.each { |x| y << x }
             end
           end
         end
 
-        # TODO Document
+        # Generates values from a sinewave discretized to +quant+ events
+        # for the duration of +dur+ cycles.
+        #
+        # Values range from -1 to 1
+        #
+        # @see #sin1 for the same function but constrained on 0 to 1 values
+        #
+        # @example
+        #   P.sin(8).map { |i| i.round(2) }
+        #     #=> [0.0, 0.71, 1.0, 0.71, 0.0, -0.71, -1.0, -0.71]
+        #
+        # @example +quant+ determines the size, +dur+ the total duration
+        #   P.sin(8).size                 #=> 8
+        #   P.sin(22).total_duration      #=> (1/1)
+        #   P.sin(19, 2).total_duration   #=> (2/1)
+        #
+        # @param quant [Fixnum]
+        # @param dur [Fixnum] (default: 1)
+        # @return [Pattern]
+        #
         def sin(quant, dur=1)
           Pattern.new(size: quant, dur: dur / quant) do |y|
             quant.times do |i|
               y << Math.sin(i / quant * 2 * Math::PI)
             end
           end
         end
 
-        # TODO Document
+        # Generates values from a sinewave discretized to +quant+ events
+        # for the duration of +dur+ cycles.
+        #
+        # Values range from 0 to 1
+        #
+        # @see #sin
+        #
+        # @example
+        #   P.sin1(8).map { |i| i.round(2) }
+        #     #=> [0.5, 0.85, 1.0, 0.85, 0.5, 0.15, 0.0, 0.15]
+        #
+        # @param quant [Fixnum]
+        # @param dur [Fixnum] (default: 1)
+        # @return [Pattern]
+        #
         def sin1(quant, dur=1)
           sin(quant, dur).scale(-1, 1, 0, 1)
         end
 
         private