ruby-changes:62746
From: Burdette <ko1@a...>
Date: Sat, 29 Aug 2020 04:56:24 +0900 (JST)
Subject: [ruby-changes:62746] 45c40f5631 (master): Comply with guide for method doc: array.c (#3469)
https://git.ruby-lang.org/ruby.git/commit/?id=45c40f5631 From 45c40f5631c6cdb14a9fe9c1b40e5fbb08793557 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Fri, 28 Aug 2020 14:56:02 -0500 Subject: Comply with guide for method doc: array.c (#3469) Methods: - freeze - try_convert - new - \<< - push - pop - shift - unshift - [] diff --git a/array.c b/array.c index 2f14194..3d90b5a 100644 --- a/array.c +++ b/array.c @@ -661,9 +661,7 @@ ary_ensure_room_for_push(VALUE ary, long add_len) https://github.com/ruby/ruby/blob/trunk/array.c#L661 * a.freeze * a.frozen? # => true * - * An attempt to modify a frozen \Array raises an exception: - * # Raises FrozenError (can't modify frozen Array: [:foo, "bar", 2]): - * [:foo, 'bar', 2].freeze.push(:foo) + * An attempt to modify a frozen \Array raises FrozenError. */ VALUE @@ -942,22 +940,16 @@ rb_check_to_array(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L940 /* * call-seq: - * Array.try_convert(object) -> new_array or nil + * Array.try_convert(object) -> object, new_array, or nil * - * Tries to convert +object+ to an \Array. + * If +object+ is an \Array object, returns +object+. * - * When +object+ is an \Array, - * returns the \Array object created by converting it: + * Otherwise if +object+ responds to <tt>:to_ary</tt>, + * calls <tt>object.to_ary</tt> and returns the result. * - * class ToAryReturnsArray < Set - * def to_ary - * self.to_a - * end - * end - * as = ToAryReturnsArray.new([:foo, :bar, :baz]) - * Array.try_convert(as) # => [:foo, :bar, :baz] + * Returns +nil+ if +object+ does not respond to <tt>:to_ary</tt> * - * Returns +nil+ if +object+ is not an Array. + * Raises an exception unless <tt>object.to_ary</tt> returns an \Array object. */ static VALUE @@ -976,32 +968,23 @@ rb_ary_s_try_convert(VALUE dummy, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L968 * * Returns a new \Array. * - * Argument +array+, if given, must be an \Array. - * Argument +size+, if given must be an \Integer. - * Argument +default_value+ may be any object. - * - * --- - * * With no block and no arguments, returns a new empty \Array object. * - * With no block and a single argument +array+, + * With no block and a single \Array argument +array+, * returns a new \Array formed from +array+: - * * a = Array.new([:foo, 'bar', 2]) * a.class # => Array * a # => [:foo, "bar", 2] * - * With no block and a single argument +size+, + * With no block and a single \Integer argument +size+, * returns a new \Array of the given size * whose elements are all +nil+: - * * a = Array.new(3) * a # => [nil, nil, nil] * - * With no block and arguments +size+ and +default_value+, + * With no block and arguments +size+ and +default_value+, * returns an \Array of the given size; * each element is that same +default_value+: - * * a = Array.new(3, 'x') * a # => ['x', 'x', 'x'] * @@ -1009,33 +992,14 @@ rb_ary_s_try_convert(VALUE dummy, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L992 * returns an \Array of the given size; * the block is called with each successive integer +index+; * the element for that +index+ is the return value from the block: - * * a = Array.new(3) { |index| "Element #{index}" } * a # => ["Element 0", "Element 1", "Element 2"] * + * Raises ArgumentError if +size+ is negative. + * * With a block and no argument, * or a single argument +0+, * ignores the block and returns a new empty \Array. - * - * With a block and arguments +size+ and +default_value+, - * gives a warning message - * ('warning: block supersedes default value argument'), - * and assigns elements from the block's return values: - * - * Array.new(4, :default) {} # => [nil, nil, nil, nil] - * - * --- - * - * Raises an exception if +size+ is a negative integer: - * - * # Raises ArgumentError (negative array size): - * Array.new(-1) - * # Raises ArgumentError (negative array size): - * Array.new(-1, :default) - * # Raises ArgumentError (negative array size): - * Array.new(-1) { |n| } - * - * Raises an exception if the single argument is neither an \Array nor an \Integer. */ static VALUE @@ -1224,7 +1188,6 @@ ary_take_first_or_last(int argc, const VALUE *argv, VALUE ary, enum ary_take_pos https://github.com/ruby/ruby/blob/trunk/array.c#L1188 * a << :baz # => [:foo, "bar", 2, :baz] * * Appends +object+ as one element, even if it is another \Array: - * * a = [:foo, 'bar', 2] * a1 = a << [3, 4] * a1 # => [:foo, "bar", 2, [3, 4]] @@ -1256,26 +1219,21 @@ rb_ary_cat(VALUE ary, const VALUE *argv, long len) https://github.com/ruby/ruby/blob/trunk/array.c#L1219 /* * call-seq: * array.push(*objects) -> self - * array.append(*objects) -> self - * - * Array#append is an alias for \Array#push. * * Appends trailing elements. * - * See also: - * - #pop: Removes and returns trailing elements. - * - #shift: Removes and returns leading elements. - * - #unshift: Prepends leading elements. - * * Appends each argument in +objects+ to +self+; returns +self+: * a = [:foo, 'bar', 2] * a.push(:baz, :bat) # => [:foo, "bar", 2, :baz, :bat] * * Appends each argument as one element, even if it is another \Array: - * * a = [:foo, 'bar', 2] * a1 = a.push([:baz, :bat], [:bam, :bad]) * a1 # => [:foo, "bar", 2, [:baz, :bat], [:bam, :bad]] + * + * Array#append is an alias for \Array#push. + * + * Related: #pop, #shift, #unshift. */ static VALUE @@ -1310,27 +1268,15 @@ rb_ary_pop(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L1268 * * Removes and returns trailing elements. * - * See also: - * - #push: Appends trailing elements. - * - #shift: Removes and returns leading elements. - * - #unshift: Prepends leading elements. - * - * Argument +n+, if given, must be an \Integer. - * - * --- - * - * When no argument is given and the array is not empty, - * removes and returns the last element in the array: - * + * When no argument is given and +self+ is not empty, + * removes and returns the last element: * a = [:foo, 'bar', 2] * a.pop # => 2 * a # => [:foo, "bar"] * * Returns +nil+ if the array is empty. * - * --- - * - * When argument +n+ is given and is non-negative and in range, + * When a non-negative \Integer argument +n+ is given and is in range, * removes and returns the last +n+ elements in a new \Array: * a = [:foo, 'bar', 2] * a.pop(2) # => ["bar", 2] @@ -1340,13 +1286,7 @@ rb_ary_pop(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L1286 * a = [:foo, 'bar', 2] * a.pop(50) # => [:foo, "bar", 2] * - * --- - * - * Raises an exception if +n+ is negative: - * - * a = [:foo, 'bar', 2] - * # Raises ArgumentError (negative array size): - * a1 = a.pop(-1) + * Related: #push, #shift, #unshift. */ static VALUE @@ -1406,15 +1346,6 @@ rb_ary_shift(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L1346 * * Removes and returns leading elements. * - * See also: - * - #push: Appends trailing elements. - * - #pop: Removes and returns trailing elements. - * - #unshift: Prepends leading elements. - * - * Argument +n+, if given, must be an \Integer. - * - * --- - * * When no argument is given, removes and returns the first element: * a = [:foo, 'bar', 2] * a.shift # => :foo @@ -1422,9 +1353,7 @@ rb_ary_shift(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L1353 * * Returns +nil+ if +self+ is empty. * - * --- - * - * When argument +n+ is given, removes the first +n+ elements; + * When positive \Integer argument +n+ is given, removes the first +n+ elements; * returns those elements in a new \Array: * a = [:foo, 'bar', 2] * a.shift(2) # => [:foo, 'bar'] @@ -1437,12 +1366,7 @@ rb_ary_shift(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L1366 * * If +n+ is zero, returns a new empty \Array; +self+ is unmodified. * - * --- - * - * Raises an exception if +n+ is negative: - * a = [:foo, 'bar', 2] - * # Raises ArgumentError (negative array size): - * a1 = a.shift(-1) + * Related: #push, #pop, #unshift. */ static VALUE @@ -1597,18 +1521,13 @@ ary_ensure_room_for_unshift(VALUE ary, int argc) https://github.com/ruby/ruby/blob/trunk/array.c#L1521 * array.unshift(*objects) -> self * array.prepend(*objects) -> self * - * Array#prepend is an alias for Array#unshift. - * - * Prepends leading elements. - * - * See also: - * - #push: Appends trailing elements. - * - #pop: Removes and returns trailing elements. - * - #shift: Removes and returns leading elements. - * * Prepends the given +objects+ to +self+: * a = [:foo, 'bar', 2] * a.unshift(:bam, :bat) # => [:bam, :bat, :foo, "bar", 2] + * + * Array#prepend is an alias for Array#unshift. + * + * Related: #push, #pop, #shift. */ static VALUE @@ -1677,18 +1596,10 @@ static VALUE rb_ary_aref2(VALUE ary, VALUE b, VALUE e); https://github.com/ruby/ruby/blob/trunk/array.c#L1596 * array[index] -> object or nil * array[start, length] -> object or nil * array[range] -> object or nil - * array.slice(index) -> object or nil - * array.slice(start, length) -> object or nil - * array.slice(range) -> object or nil * * Returns elements from +self+; does not modify +self+. * - * - Arguments +index+, +start+, and +length+, if given, must be Integers. - * - Argument +range+, if given, must be a \Range object. - * - * --- - * - * When a single argument +index+ is given, returns the element at offset +index+: + * When a single \Integer argument +index+ is given, returns the element at offset +index+: * a = [:foo, 'bar', 2] * a[0] # => :foo * a[2] # => 2 @@ -1701,9 +1612,7 @@ static VALUE rb_ary_aref2(VALUE ary, VALUE b, VALUE e); https://githu (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/