merge revision(s) 57434: [Backport #13161]

	Enumerable#{min,min_by,max,max_by} [ci skip]

	* enum.c: [DOC] Enumerable#{min,min_by,max,max_by} return a sorted
	  array when +n+ argument is used.

	* enum.c: Small typo : minimum -> maximum

	[Bug #13161]
	Author:    Eric Duminil <eric.duminil@gmail.com>

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_2_4@57876 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

2 files changed, 10 insertions, 6 deletions

diff --git a/enum.c b/enum.c
index 310db3f1df..70b7729c88 100644
--- a/enum.c
+++ b/enum.c
@@ -1563,11 +1563,12 @@ min_ii(RB_BLOCK_CALL_FUNC_ARGLIST(i, args))
  *     a.min { |a, b| a.length <=> b.length }  #=> "dog"
  *
  *  If the +n+ argument is given, minimum +n+ elements are returned
- *  as an array.
+ *  as a sorted array.
  *
  *     a = %w[albatross dog horse]
  *     a.min(2)                                  #=> ["albatross", "dog"]
  *     a.min(2) {|a, b| a.length <=> b.length }  #=> ["dog", "horse"]
+ *     [5, 1, 3, 4, 2].min(3)                    #=> [1, 2, 3]
  */
 
 static VALUE
@@ -1656,11 +1657,12 @@ max_ii(RB_BLOCK_CALL_FUNC_ARGLIST(i, args))
  *     a.max { |a, b| a.length <=> b.length }  #=> "albatross"
  *
  *  If the +n+ argument is given, maximum +n+ elements are returned
- *  as an array.
+ *  as an array, sorted in descending order.
  *
  *     a = %w[albatross dog horse]
  *     a.max(2)                                  #=> ["horse", "dog"]
  *     a.max(2) {|a, b| a.length <=> b.length }  #=> ["albatross", "horse"]
+ *     [5, 1, 3, 4, 2].max(3)                    #=> [5, 4, 3]
  */
 
 static VALUE
@@ -1878,7 +1880,8 @@ min_by_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, args))
  *     a.min_by { |x| x.length }   #=> "dog"
  *
  *  If the +n+ argument is given, minimum +n+ elements are returned
- *  as an array.
+ *  as an array. These +n+ elements are sorted by the value from the
+ *  given block.
  *
  *     a = %w[albatross dog horse]
  *     p a.min_by(2) {|x| x.length } #=> ["dog", "horse"]
@@ -1937,8 +1940,9 @@ max_by_i(RB_BLOCK_CALL_FUNC_ARGLIST(i, args))
  *     a = %w(albatross dog horse)
  *     a.max_by { |x| x.length }   #=> "albatross"
  *
- *  If the +n+ argument is given, minimum +n+ elements are returned
- *  as an array.
+ *  If the +n+ argument is given, maximum +n+ elements are returned
+ *  as an array. These +n+ elements are sorted by the value from the
+ *  given block, in descending order.
  *
  *     a = %w[albatross dog horse]
  *     a.max_by(2) {|x| x.length } #=> ["albatross", "horse"]
diff --git a/version.h b/version.h
index 81f02bd3cf..79b856b59e 100644
--- a/version.h
+++ b/version.h
@@ -1,6 +1,6 @@
 #define RUBY_VERSION "2.4.0"
 #define RUBY_RELEASE_DATE "2017-03-12"
-#define RUBY_PATCHLEVEL 41
+#define RUBY_PATCHLEVEL 42
 
 #define RUBY_RELEASE_YEAR 2017
 #define RUBY_RELEASE_MONTH 3