ruby-changes:62796
From: Burdette <ko1@a...>
Date: Wed, 2 Sep 2020 02:50:14 +0900 (JST)
Subject: [ruby-changes:62796] 94430d009a (master): Comply with guide for method doc: array.c (#3499)
https://git.ruby-lang.org/ruby.git/commit/?id=94430d009a From 94430d009a7018c9d6447fe6814a51b664ad46a9 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Tue, 1 Sep 2020 12:49:48 -0500 Subject: Comply with guide for method doc: array.c (#3499) Methods considered: count flatten! flatten cycle permutation combination repeated_permutation repeated_combination product take take_while drop drop_while diff --git a/array.c b/array.c index 82cc017..2a1a8f5 100644 --- a/array.c +++ b/array.c @@ -6083,9 +6083,7 @@ flatten(VALUE ary, int level) https://github.com/ruby/ruby/blob/trunk/array.c#L6083 * Replaces each nested \Array in +self+ with the elements from that \Array; * returns +self+ if any changes, +nil+ otherwise. * - * Argument +level+, if given and not +nil+, must be an \Integer. - * - * With non-negative argument +level+, flattens recursively through +level+ levels: + * With non-negative \Integer argument +level+, flattens recursively through +level+ levels: * a = [ 0, [ 1, [2, 3], 4 ], 5 ] * a.flatten!(1) # => [0, 1, [2, 3], 4, 5] * a = [ 0, [ 1, [2, 3], 4 ], 5 ] @@ -6103,14 +6101,6 @@ flatten(VALUE ary, int level) https://github.com/ruby/ruby/blob/trunk/array.c#L6101 * a = [ 0, [ 1, [2, 3], 4 ], 5 ] * a.flatten!(-2) # => [0, 1, 2, 3, 4, 5] * [0, 1, 2].flatten!(-1) # => nil - * - * --- - * - * Raises an exception if +self+ contains a circular reference: - * a = [] - * a.push([a, a]) - * # Raises ArgumentError (tried to flatten recursive array): - * a.flatten! */ static VALUE @@ -6144,9 +6134,7 @@ rb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L6134 * - Each non-Array element is unchanged. * - Each \Array is replaced by its individual elements. * - * Argument +level+, if given and not +nil+, must be Integers. - * - * With non-negative argument +level+, flattens recursively through +level+ levels: + * With non-negative \Integer argument +level+, flattens recursively through +level+ levels: * a = [ 0, [ 1, [2, 3], 4 ], 5 ] * a.flatten(0) # => [0, [1, [2, 3], 4], 5] * a = [ 0, [ 1, [2, 3], 4 ], 5 ] @@ -6165,14 +6153,6 @@ rb_ary_flatten_bang(int argc, VALUE *argv, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L6153 * a = [ 0, [ 1, [2, 3], 4 ], 5 ] * a.flatten(-2) # => [0, 1, 2, 3, 4, 5] * [0, 1, 2].flatten(-1) # => [0, 1, 2] - * - * --- - * - * Raises an exception if +self+ contains a circular reference: - * a = [] - * a.push([a, a]) - * # Raises ArgumentError (tried to flatten recursive array): - * a.flatten */ static VALUE @@ -6379,11 +6359,7 @@ rb_ary_cycle_size(VALUE self, VALUE args, VALUE eobj) https://github.com/ruby/ruby/blob/trunk/array.c#L6359 * array.cycle -> new_enumerator * array.cycle(count) -> new_enumerator * - * Argument +count+, if given, must be +nil+ or an \Integer. - * - * --- - * - * When called with positive argument +count+ and a block, + * When called with positive \Integer argument +count+ and a block, * calls the block with each element, then does so again, * until it has done so +count+ times; returns +nil+: * output = [] @@ -6394,15 +6370,11 @@ rb_ary_cycle_size(VALUE self, VALUE args, VALUE eobj) https://github.com/ruby/ruby/blob/trunk/array.c#L6370 * [0, 1].cycle(0) {|element| fail 'Cannot happen' } # => nil * [0, 1].cycle(-1) {|element| fail 'Cannot happen' } # => nil * - * --- - * * When a block is given, and argument is omitted or +nil+, cycles forever: * # Prints 0 and 1 forever. * [0, 1].cycle {|element| puts element } * [0, 1].cycle(nil) {|element| puts element } * - * --- - * * When no block is given, returns a new \Enumerator: * * [0, 1].cycle(2) # => #<Enumerator: [0, 1]:cycle(2)> @@ -6562,11 +6534,7 @@ rb_ary_permutation_size(VALUE ary, VALUE args, VALUE eobj) https://github.com/ruby/ruby/blob/trunk/array.c#L6534 * When invoked with a block, yield all permutations of elements of +self+; returns +self+. * The order of permutations is indeterminate. * - * Argument +n+, if given, must be an \Integer. - * - * --- - * - * When a block and an in-range positive argument +n+ (<tt>0 < n <= self.size</tt>) + * When a block and an in-range positive \Integer argument +n+ (<tt>0 < n <= self.size</tt>) * are given, calls the block with all +n+-tuple permutations of +self+. * * Example: @@ -6590,24 +6558,18 @@ rb_ary_permutation_size(VALUE ary, VALUE args, VALUE eobj) https://github.com/ruby/ruby/blob/trunk/array.c#L6558 * [2, 0, 1] * [2, 1, 0] * - * --- - * * When +n+ is zero, calls the block once with a new empty \Array: * a = [0, 1, 2] * a.permutation(0) {|permutation| p permutation } * Output: * [] * - * --- - * * When +n+ is out of range (negative or larger than <tt>self.size</tt>), * does not call the block: * a = [0, 1, 2] * a.permutation(-1) {|permutation| fail 'Cannot happen' } * a.permutation(4) {|permutation| fail 'Cannot happen' } * - * --- - * * When a block given but no argument, * behaves the same as <tt>a.permutation(a.size)</tt>: * a = [0, 1, 2] @@ -6620,8 +6582,6 @@ rb_ary_permutation_size(VALUE ary, VALUE args, VALUE eobj) https://github.com/ruby/ruby/blob/trunk/array.c#L6582 * [2, 0, 1] * [2, 1, 0] * - * --- - * * Returns a new \Enumerator if no block given: * a = [0, 1, 2] * a.permutation # => #<Enumerator: [0, 1, 2]:permutation> @@ -6704,11 +6664,7 @@ rb_ary_combination_size(VALUE ary, VALUE args, VALUE eobj) https://github.com/ruby/ruby/blob/trunk/array.c#L6664 * Calls the block, if given, with combinations of elements of +self+; * returns +self+. The order of combinations is indeterminate. * - * Argument +n+, if given, must be an \Integer. - * - * --- - * - * When a block and an in-range positive argument +n+ (<tt>0 < n <= self.size</tt>) + * When a block and an in-range positive \Integer argument +n+ (<tt>0 < n <= self.size</tt>) * are given, calls the block with all +n+-tuple combinations of +self+. * * Example: @@ -6725,24 +6681,18 @@ rb_ary_combination_size(VALUE ary, VALUE args, VALUE eobj) https://github.com/ruby/ruby/blob/trunk/array.c#L6681 * Output: * [0, 1, 2] * - * --- - * * When +n+ is zero, calls the block once with a new empty \Array: * a = [0, 1, 2] * a1 = a.combination(0) {|combination| p combination } * Output: * [] * - * --- - * * When +n+ is out of range (negative or larger than <tt>self.size</tt>), * does not call the block: * a = [0, 1, 2] * a.combination(-1) {|combination| fail 'Cannot happen' } * a.combination(4) {|combination| fail 'Cannot happen' } * - * --- - * * Returns a new \Enumerator if no block given: * a = [0, 1, 2] * a.combination(2) # => #<Enumerator: [0, 1, 2]:combination(2)> @@ -6839,11 +6789,7 @@ rb_ary_repeated_permutation_size(VALUE ary, VALUE args, VALUE eobj) https://github.com/ruby/ruby/blob/trunk/array.c#L6789 * each permutation is an \Array; * returns +self+. The order of the permutations is indeterminate. * - * Argument +n+ must be an \Integer. - * - * --- - * - * When a block and a positive argument +n+ are given, calls the block with each + * 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>. * @@ -6873,8 +6819,6 @@ rb_ary_repeated_permutation_size(VALUE ary, VALUE args, VALUE eobj) https://github.com/ruby/ruby/blob/trunk/array.c#L6819 * If +n+ is negative, does not call the block: * a.repeated_permutation(-1) {|permutation| fail 'Cannot happen' } * - * --- - * * Returns a new \Enumerator if no block given: * a = [0, 1, 2] * a.repeated_permutation(2) # => #<Enumerator: [0, 1, 2]:permutation(2)> @@ -6967,11 +6911,7 @@ rb_ary_repeated_combination_size(VALUE ary, VALUE args, VALUE eobj) https://github.com/ruby/ruby/blob/trunk/array.c#L6911 * each combination is an \Array; * returns +self+. The order of the combinations is indeterminate. * - * Argument +n+ must be an \Integer. - * - * --- - * - * When a block and a positive argument +n+ are given, calls the block with each + * When a block and a positive \Integer argument +n+ are given, calls the block with each * +n+-tuple repeated combination of the elements of +self+. * The number of combinations is <tt>(n+1)(n+2)/2</tt>. * @@ -6998,8 +6938,6 @@ rb_ary_repeated_combination_size(VALUE ary, VALUE args, VALUE eobj) https://github.com/ruby/ruby/blob/trunk/array.c#L6938 * If +n+ is negative, does not call the block: * a.repeated_combination(-1) {|combination| fail 'Cannot happen' } * - * --- - * * Returns a new \Enumerator if no block given: * a = [0, 1, 2] * a.repeated_combination(2) # => #<Enumerator: [0, 1, 2]:combination(2)> @@ -7057,16 +6995,12 @@ rb_ary_repeated_combination(VALUE ary, VALUE num) https://github.com/ruby/ruby/blob/trunk/array.c#L6995 * array.product(*other_arrays) -> new_array * array.product(*other_arrays) {|combination| ... } -> self * - * Computes and returns or yields all combinations of elements from all the arrays, + * Computes and returns or yields all combinations of elements from all the Arrays, * including both +self+ and +other_arrays+. * - The number of combinations is the product of the sizes of all the arrays, * including both +self+ and +other_arrays+. * - The order of the returned combinations is indeterminate. * - * Each argument must be an \Array. - * - * --- - * * When no block is given, returns the combinations as an \Array of Arrays: * a = [0, 1, 2] * a1 = [3, 4] @@ -7084,8 +7018,6 @@ rb_ary_repeated_combination(VALUE ary, VALUE num) https://github.com/ruby/ruby/blob/tr (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/