[DOC] Tweaks for Array#repeated_permutation (#11873)

BurdetteLamar · web-flow · commit c51947671ee3 · 2024-10-11T11:12:12.000-04:00
diff --git a/array.c b/array.c
@@ -7213,68 +7213,41 @@ rb_ary_repeated_permutation_size(VALUE ary, VALUE args, VALUE eobj)
 
 /*
  *  call-seq:
- *    array.repeated_permutation(n) {|permutation| ... } -> self
- *    array.repeated_permutation(n) -> new_enumerator
+ *    repeated_permutation(size) {|permutation| ... } -> self
+ *    repeated_permutation(size) -> new_enumerator
  *
- *  Calls the block with each repeated permutation of length +n+ of the elements of +self+;
- *  each permutation is an +Array+;
+ *  With a block given, calls the block with each repeated permutation of length +size+
+ *  of the elements of +self+;
+ *  each permutation is an array;
  *  returns +self+. The order of the permutations is indeterminate.
  *
- *  When a block and a positive Integer argument +n+ are given, calls the block with each
- *  +n+-tuple repeated permutation of the elements of +self+.
- *  The number of permutations is <tt>self.size**n</tt>.
- *
- *  +n+ = 1:
- *
- *    a = [0, 1, 2]
- *    a.repeated_permutation(1) {|permutation| p permutation }
- *
- *  Output:
- *
- *    [0]
- *    [1]
- *    [2]
- *
- *  +n+ = 2:
- *
- *    a.repeated_permutation(2) {|permutation| p permutation }
+ *  If a positive integer argument +size+ is given,
+ *  calls the block with each +size+-tuple repeated permutation of the elements of +self+.
+ *  The number of permutations is <tt>self.size**size</tt>.
  *
- *  Output:
+ *  Examples:
  *
- *    [0, 0]
- *    [0, 1]
- *    [0, 2]
- *    [1, 0]
- *    [1, 1]
- *    [1, 2]
- *    [2, 0]
- *    [2, 1]
- *    [2, 2]
+ *  - +size+ is 1:
  *
- *  If +n+ is zero, calls the block once with an empty +Array+.
+ *      p = []
+ *      [0, 1, 2].repeated_permutation(1) {|permutation| p.push(permutation) }
+ *      p # => [[0], [1], [2]]
  *
- *  If +n+ is negative, does not call the block:
+ *  - +size+ is 2:
  *
- *    a.repeated_permutation(-1) {|permutation| fail 'Cannot happen' }
+ *      p = []
+ *      [0, 1, 2].repeated_permutation(2) {|permutation| p.push(permutation) }
+ *      p # => [[0, 0], [0, 1], [0, 2], [1, 0], [1, 1], [1, 2], [2, 0], [2, 1], [2, 2]]
  *
- *  Returns a new Enumerator if no block given:
+ *  If +size+ is zero, calls the block once with an empty array.
  *
- *    a = [0, 1, 2]
- *    a.repeated_permutation(2) # => #<Enumerator: [0, 1, 2]:permutation(2)>
+ *  If +size+ is negative, does not call the block:
  *
- *  Using Enumerators, it's convenient to show the permutations and counts
- *  for some values of +n+:
+ *    [0, 1, 2].repeated_permutation(-1) {|permutation| fail 'Cannot happen' }
  *
- *    e = a.repeated_permutation(0)
- *    e.size # => 1
- *    e.to_a # => [[]]
- *    e = a.repeated_permutation(1)
- *    e.size # => 3
- *    e.to_a # => [[0], [1], [2]]
- *    e = a.repeated_permutation(2)
- *    e.size # => 9
- *    e.to_a # => [[0, 0], [0, 1], [0, 2], [1, 0], [1, 1], [1, 2], [2, 0], [2, 1], [2, 2]]
+ *  With no block given, returns a new Enumerator.
  *
+ *  Related: see {Methods for Combining}[rdoc-ref:Array@Methods+for+Combining].
  */
 static VALUE
 rb_ary_repeated_permutation(VALUE ary, VALUE num)
