From 726f2e59f9b0c7a69f540e09bab54ab17b013d56 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Sat, 29 Aug 2020 15:16:02 -0500 Subject: Comply with guide for method doc: array.c (#3474) Methods considered: length empty? join inspect to_a to_h to_ary reverse! reverse rotate! rotate sort! sort --- array.c | 95 +++++++++-------------------------------------------------------- 1 file changed, 13 insertions(+), 82 deletions(-) diff --git a/array.c b/array.c index 2c8f8d9873..880cf01aa6 100644 --- a/array.c +++ b/array.c @@ -2492,10 +2492,7 @@ rb_ary_reverse_each(VALUE ary) * call-seq: * array.length -> an_integer * - * Returns the count of elements in the array: - * a = [:foo, 'bar', 2] - * a.length # => 3 - * [].length # => 0 + * Returns the count of elements in +self+. */ static VALUE @@ -2509,10 +2506,8 @@ rb_ary_length(VALUE ary) * call-seq: * array.empty? -> true or false * - * Returns +true+ if the count of elements in the array is zero, - * +false+ otherwise: - * [].empty? # => true - * [:foo, 'bar', 2].empty? # => false + * Returns +true+ if the count of elements in +self+ is zero, + * +false+ otherwise. */ static VALUE @@ -2686,21 +2681,15 @@ rb_ary_join(VALUE ary, VALUE sep) * - Uses element.to_s if +element+ is not a kind_of?(Array). * - Uses recursive element.join(separator) if +element+ is a kind_of?(Array). * - * Argument +separator+, if given, must be a \String. - * - * --- - * * With no argument, joins using the output field separator, $,: * a = [:foo, 'bar', 2] * $, # => nil * a.join # => "foobar2" * - * With argument +separator+, joins using that separator: + * With \string argument +separator+, joins using that separator: * a = [:foo, 'bar', 2] * a.join("\n") # => "foo\nbar\n2" * - * --- - * * Joins recursively for nested Arrays: * a = [:foo, [:bar, [:baz, :bat]]] * a.join # => "foobarbazbat" @@ -2741,19 +2730,13 @@ inspect_ary(VALUE ary, VALUE dummy, int recur) /* * call-seq: * array.inspect -> new_string - * array.to_s => new_string - * - * Array#to_s is an alias for Array#inspect. * * Returns the new \String formed by calling method #inspect * on each array element: * a = [:foo, 'bar', 2] * a.inspect # => "[:foo, \"bar\", 2]" * - * Raises an exception if any element lacks instance method #inspect: - * a = [:foo, 'bar', 2, BasicObject.new] - * a.inspect - * # Raises NoMethodError (undefined method `inspect' for #) + * Array#to_s is an alias for Array#inspect. */ static VALUE @@ -2818,20 +2801,6 @@ rb_ary_to_a(VALUE ary) * a = [['foo', 'zero'], ['bar', 'one'], ['baz', 'two']] * h = a.to_h * h # => {"foo"=>"zero", "bar"=>"one", "baz"=>"two"} - * - * --- - * - * Raises an exception if no block is given - * and any element in +self+ is not a 2-element \Array: - * # Raises TypeError (wrong element type Symbol at 0 (expected array): - * [:foo].to_h - * # Raises ArgumentError (wrong array length at 0 (expected 2, was 1)): - * [[:foo]].to_h - * - * Raises an exception if for some 2-element \Array +element+ in +self+, - * element.first would be an invalid hash key: - * # Raises NoMethodError (undefined method `hash' for #): - * [[BasicObject.new, 0]].to_h */ static VALUE @@ -2862,9 +2831,7 @@ rb_ary_to_h(VALUE ary) * call-seq: * array.to_ary -> self * - * Returns +self+: - * a = [:foo, 'bar', 2] - * a.to_ary # => [:foo, "bar", 2] + * Returns +self+. */ static VALUE @@ -2918,7 +2885,7 @@ rb_ary_reverse_bang(VALUE ary) * call-seq: * array.reverse -> new_array * - * Returns a new \Array whose elements are in reverse order: + * Returns a new \Array with the elements of +self+ in reverse order. * a = ['foo', 'bar', 'two'] * a1 = a.reverse * a1 # => ["two", "bar", "foo"] @@ -2986,17 +2953,12 @@ rb_ary_rotate(VALUE ary, long cnt) * * Rotates +self+ in place by moving elements from one end to the other; returns +self+. * - * Argument +count+, if given, must be an \Integer. - * - * --- - * * When no argument given, rotates the first element to the last position: * a = [:foo, 'bar', 2, 'bar'] * a.rotate! # => ["bar", 2, "bar", :foo] * - * --- - * - * When given a non-negative +count+, rotates +count+ elements from the beginning to the end: + * When given a non-negative \Integer +count+, + * rotates +count+ elements from the beginning to the end: * a = [:foo, 'bar', 2] * a.rotate!(2) * a # => [2, :foo, "bar"] @@ -3011,9 +2973,7 @@ rb_ary_rotate(VALUE ary, long cnt) * a.rotate!(0) * a # => [:foo, "bar", 2] * - * --- - * - * When given a negative +count+, rotates in the opposite direction, + * When given a negative Integer +count+, rotates in the opposite direction, * from end to beginning: * a = [:foo, 'bar', 2] * a.rotate!(-2) @@ -3041,18 +3001,13 @@ rb_ary_rotate_bang(int argc, VALUE *argv, VALUE ary) * Returns a new \Array formed from +self+ with elements * rotated from one end to the other. * - * Argument +count+, if given, must be an \Integer. - * - * --- * When no argument given, returns a new \Array that is like +self+, * except that the first element has been rotated to the last position: * a = [:foo, 'bar', 2, 'bar'] * a1 = a.rotate * a1 # => ["bar", 2, "bar", :foo] * - * --- - * - * When given a non-negative +count+, + * When given a non-negative \Integer +count+, * returns a new \Array with +count+ elements rotated from the beginning to the end: * a = [:foo, 'bar', 2] * a1 = a.rotate(2) @@ -3068,9 +3023,7 @@ rb_ary_rotate_bang(int argc, VALUE *argv, VALUE ary) * a1 = a.rotate(0) * a1 # => [:foo, "bar", 2] * - * --- - * - * When given a negative +count+, rotates in the opposite direction, + * When given a negative \Integer +count+, rotates in the opposite direction, * from end to beginning: * a = [:foo, 'bar', 2] * a1 = a.rotate(-2) @@ -3168,8 +3121,6 @@ sort_2(const void *ap, const void *bp, void *dummy) * * Returns +self+ with its elements sorted in place. * - * --- - * * With no block, compares elements using operator <=> * (see Comparable): * a = 'abcde'.split('').shuffle @@ -3177,8 +3128,6 @@ sort_2(const void *ap, const void *bp, void *dummy) * a.sort! * a # => ["a", "b", "c", "d", "e"] * - * --- - * * With a block, calls the block with each element pair; * for each element pair +a+ and +b+, the block should return an integer: * - Negative when +b+ is to follow +a+. @@ -3199,13 +3148,6 @@ sort_2(const void *ap, const void *bp, void *dummy) * a # => ["e", "b", "d", "a", "c"] * a.sort! {|a, b| 0 } * a # => ["d", "e", "c", "a", "b"] - * - * --- - * - * Raises an exception if the block returns a non-Integer: - * a = 'abcde'.split('').shuffle - * # Raises ArgumentError (comparison of Symbol with 0 failed): - * a1 = a.sort! {|a, b| :foo } */ VALUE @@ -3275,10 +3217,6 @@ rb_ary_sort_bang(VALUE ary) * * Returns a new \Array whose elements are those from +self+, sorted. * - * See also Enumerable#sort_by. - * - * --- - * * With no block, compares elements using operator <=> * (see Comparable): * a = 'abcde'.split('').shuffle @@ -3286,8 +3224,6 @@ rb_ary_sort_bang(VALUE ary) * a1 = a.sort * a1 # => ["a", "b", "c", "d", "e"] * - * --- - * * With a block, calls the block with each element pair; * for each element pair +a+ and +b+, the block should return an integer: * - Negative when +b+ is to follow +a+. @@ -3309,12 +3245,7 @@ rb_ary_sort_bang(VALUE ary) * a1 = a.sort {|a, b| 0 } * a1 # => ["c", "e", "b", "d", "a"] * - * --- - * - * Raises an exception if the block returns a non-Integer: - * a = 'abcde'.split('').shuffle - * # Raises ArgumentError (comparison of Symbol with 0 failed): - * a1 = a.sort {|a, b| :foo } + * Related: Enumerable#sort_by. */ VALUE -- cgit v1.2.3