ruby-changes:62763
From: Burdette <ko1@a...>
Date: Mon, 31 Aug 2020 00:34:33 +0900 (JST)
Subject: [ruby-changes:62763] 585a659b1e (master): Comply with guide for method doc: array.c (#3475)
https://git.ruby-lang.org/ruby.git/commit/?id=585a659b1e From 585a659b1e8b3361192156cce218d8df0ef82f97 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Sun, 30 Aug 2020 10:34:13 -0500 Subject: Comply with guide for method doc: array.c (#3475) Methods considered: bsearch bsearch_index sort_by! collect collect! values_at select select! keep_if delete diff --git a/array.c b/array.c index 880cf01..ebd5cc5 100644 --- a/array.c +++ b/array.c @@ -3276,7 +3276,7 @@ static VALUE rb_ary_bsearch_index(VALUE ary); https://github.com/ruby/ruby/blob/trunk/array.c#L3276 * The block should not mix the modes by and sometimes returning +true+ or +false+ * and sometimes returning a numeric value, but this is not checked. * - * ====== Find-Minimum Mode + * <b>Find-Minimum Mode</b> * * In find-minimum mode, the block always returns +true+ or +false+. * The further requirement (though not checked) is that @@ -3307,7 +3307,7 @@ static VALUE rb_ary_bsearch_index(VALUE ary); https://github.com/ruby/ruby/blob/trunk/array.c#L3307 * a = [0, 4, 7, 10, 12] * a.map {|x| x == 7 } # => [false, false, true, false, false] * - * ====== Find-Any Mode + * <b>Find-Any Mode</b> * * In find-any mode, the block always returns a numeric value. * The further requirement (though not checked) is that @@ -3344,18 +3344,9 @@ static VALUE rb_ary_bsearch_index(VALUE ary); https://github.com/ruby/ruby/blob/trunk/array.c#L3344 * a = [0, 4, 7, 10, 12] * a.map {|element| element <=> 7 } # => [-1, -1, 0, 1, 1] * - * --- - * * Returns an enumerator if no block given: * a = [0, 4, 7, 10, 12] * a.bsearch # => #<Enumerator: [0, 4, 7, 10, 12]:bsearch> - * - * --- - * - * Raises an exception if the block returns an invalid value: - * a = 'abcde'.split('').shuffle - * # Raises TypeError (wrong argument type Symbol (must be numeric, true, false or nil)): - * a.bsearch {|element| :foo } */ static VALUE @@ -3450,8 +3441,6 @@ sort_by_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, dummy)) https://github.com/ruby/ruby/blob/trunk/array.c#L3441 * a.sort_by! {|element| element.size } * a # => ["d", "cc", "bbb", "aaaa"] * - * --- - * * Returns a new \Enumerator if no block given: * * a = ['aaaa', 'bbb', 'cc', 'd'] @@ -3475,23 +3464,19 @@ rb_ary_sort_by_bang(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L3464 * call-seq: * array.map {|element| ... } -> new_array * array.map -> new_enumerator - * array.collect {|element| ... } -> new_array - * array.collect -> new_enumerator - * - * Array#map is an alias for Array#collect. * * Calls the block, if given, with each element of +self+; * returns a new \Array whose elements are the return values from the block: * a = [:foo, 'bar', 2] - * a1 = a.collect {|element| element.class } + * a1 = a.map {|element| element.class } * a1 # => [Symbol, String, Integer] * - * --- - * * Returns a new \Enumerator if no block given: * a = [:foo, 'bar', 2] - * a1 = a.collect - * a1 # => #<Enumerator: [:foo, "bar", 2]:collect> + * a1 = a.map + * a1 # => #<Enumerator: [:foo, "bar", 2]:map> + * + * Array#collect is an alias for Array#map. */ static VALUE @@ -3513,22 +3498,18 @@ rb_ary_collect(VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L3498 * call-seq: * array.map! {|element| ... } -> self * array.map! -> new_enumerator - * array.collect! {|element| ... } -> self - * array.collect! -> new_enumerator - * - * Array#map! is an alias for Array#collect!. * * Calls the block, if given, with each element; * replaces the element with the block's return value: * a = [:foo, 'bar', 2] - * a.collect! { |element| element.class } # => [Symbol, String, Integer] - * - * --- + * a.map! { |element| element.class } # => [Symbol, String, Integer] * * Returns a new \Enumerator if no block given: * a = [:foo, 'bar', 2] - * a1 = a.collect! - * a1 # => #<Enumerator: [:foo, "bar", 2]:collect!> + * a1 = a.map! + * a1 # => #<Enumerator: [:foo, "bar", 2]:map!> + * + * Array#collect! is an alias for Array#map!. */ static VALUE @@ -3603,11 +3584,7 @@ append_values_at_single(VALUE result, VALUE ary, long olen, VALUE idx) https://github.com/ruby/ruby/blob/trunk/array.c#L3584 * array.values_at(*indexes) -> new_array * * Returns a new \Array whose elements are the elements - * of +self+ at the given +indexes+. - * - * Each +index+ given in +indexes+ must be an \Integer. - * - * --- + * of +self+ at the given \Integer +indexes+. * * For each positive +index+, returns the element at offset +index+: * a = [:foo, 'bar', 2] @@ -3623,8 +3600,6 @@ append_values_at_single(VALUE result, VALUE ary, long olen, VALUE idx) https://github.com/ruby/ruby/blob/trunk/array.c#L3600 * * Returns a new empty \Array if no arguments given. * - * --- - * * For each negative +index+, counts backward from the end of the array: * a = [:foo, 'bar', 2] * a.values_at(-1, -3) # => [2, :foo] @@ -3655,10 +3630,6 @@ rb_ary_values_at(int argc, VALUE *argv, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L3630 * call-seq: * array.select {|element| ... } -> new_array * array.select -> new_enumerator - * array.filter {|element| ... } -> new_array - * array.filter -> new_enumerator - * - * Array#filter is an alias for Array#select. * * Calls the block, if given, with each element of +self+; * returns a new \Array containing those elements of +self+ @@ -3667,11 +3638,11 @@ rb_ary_values_at(int argc, VALUE *argv, VALUE ary) https://github.com/ruby/ruby/blob/trunk/array.c#L3638 * a1 = a.select {|element| element.to_s.start_with?('b') } * a1 # => ["bar", :bam] * - * --- - * * Returns a new \Enumerator if no block given: * a = [:foo, 'bar', 2, :bam] * a.select # => #<Enumerator: [:foo, "bar", 2, :bam]:select> + * + * Array#filter is an alias for Array#select. */ static VALUE @@ -3738,10 +3709,6 @@ select_bang_ensure(VALUE a) https://github.com/ruby/ruby/blob/trunk/array.c#L3709 * call-seq: * array.select! {|element| ... } -> self or nil * array.select! -> new_enumerator - * array.filter! {|element| ... } -> self or nil - * array.filter! -> new_enumerator - * - * Array#filter! is an alias for Array#select!. * * Calls the block, if given with each element of +self+; * removes from +self+ those elements for which the block returns +false+ or +nil+. @@ -3752,11 +3719,11 @@ select_bang_ensure(VALUE a) https://github.com/ruby/ruby/blob/trunk/array.c#L3719 * * Returns +nil+ if no elements were removed. * - * --- - * * Returns a new \Enumerator if no block given: * a = [:foo, 'bar', 2, :bam] * a.select! # => #<Enumerator: [:foo, "bar", 2, :bam]:select!> + * + * Array#filter! is an alias for Array#select!. */ static VALUE @@ -3815,8 +3782,6 @@ ary_resize_smaller(VALUE ary, long len) https://github.com/ruby/ruby/blob/trunk/array.c#L3782 * * Removes zero or more elements from +self+; returns +self+. * - * --- - * * When no block is given, * removes from +self+ each element +ele+ such that <tt>ele == obj</tt>; * returns the last deleted element: @@ -3827,8 +3792,6 @@ ary_resize_smaller(VALUE ary, long len) https://github.com/ruby/ruby/blob/trunk/array.c#L3792 * * Returns +nil+ if no elements removed. * - * --- - * * When a block is given, * removes from +self+ each element +ele+ such that <tt>ele == obj</tt>. * -- cgit v0.10.2 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/