From 0e5aecea11d6d214bf578edfbbdb126ceb4762cb Mon Sep 17 00:00:00 2001
From: Nobuyoshi Nakada <nobu@ruby-lang.org>
Date: Wed, 10 May 2023 15:47:39 +0900
Subject: [PATCH] [DOC] Move docs of `Array#first` and `Array#last` to array.rb

---
 array.c  | 67 --------------------------------------------------------
 array.rb | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+), 67 deletions(-)

diff --git a/array.c b/array.c
index 622e17905d..fc7eebd050 100644
--- a/array.c
+++ b/array.c
@@ -2003,39 +2003,6 @@ rb_ary_at(VALUE ary, VALUE pos)
 }
 
 #if 0
-/*
- *  call-seq:
- *    array.first -> object or nil
- *    array.first(n) -> new_array
- *
- *  Returns elements from +self+; does not modify +self+.
- *
- *  When no argument is given, returns the first element:
- *
- *    a = [:foo, 'bar', 2]
- *    a.first # => :foo
- *    a # => [:foo, "bar", 2]
- *
- *  If +self+ is empty, returns +nil+.
- *
- *  When non-negative \Integer argument +n+ is given,
- *  returns the first +n+ elements in a new \Array:
- *
- *    a = [:foo, 'bar', 2]
- *    a.first(2) # => [:foo, "bar"]
- *
- *  If <tt>n >= array.size</tt>, returns all elements:
- *
- *    a = [:foo, 'bar', 2]
- *    a.first(50) # => [:foo, "bar", 2]
- *
- *  If <tt>n == 0</tt> returns an new empty \Array:
- *
- *    a = [:foo, 'bar', 2]
- *    a.first(0) # []
- *
- *  Related: #last.
- */
 static VALUE
 rb_ary_first(int argc, VALUE *argv, VALUE ary)
 {
@@ -2062,40 +2029,6 @@ ary_last(VALUE self)
     return (len == 0) ? Qnil : RARRAY_AREF(self, len-1);
 }
 
-/*
- *  call-seq:
- *    array.last  -> object or nil
- *    array.last(n) -> new_array
- *
- *  Returns elements from +self+; +self+ is not modified.
- *
- *  When no argument is given, returns the last element:
- *
- *    a = [:foo, 'bar', 2]
- *    a.last # => 2
- *    a # => [:foo, "bar", 2]
- *
- *  If +self+ is empty, returns +nil+.
- *
- *  When non-negative \Integer argument +n+ is given,
- *  returns the last +n+ elements in a new \Array:
- *
- *    a = [:foo, 'bar', 2]
- *    a.last(2) # => ["bar", 2]
- *
- *  If <tt>n >= array.size</tt>, returns all elements:
- *
- *    a = [:foo, 'bar', 2]
- *    a.last(50) # => [:foo, "bar", 2]
- *
- *  If <tt>n == 0</tt>, returns an new empty \Array:
- *
- *    a = [:foo, 'bar', 2]
- *    a.last(0) # []
- *
- *  Related: #first.
- */
-
 VALUE
 rb_ary_last(int argc, const VALUE *argv, VALUE ary) // used by parse.y
 {
diff --git a/array.rb b/array.rb
index 728438f558..358b6a5d79 100644
--- a/array.rb
+++ b/array.rb
@@ -67,6 +67,37 @@ class Array
     end
   end
 
+  # call-seq:
+  #   array.first -> object or nil
+  #   array.first(n) -> new_array
+  #
+  # Returns elements from +self+; does not modify +self+.
+  #
+  # When no argument is given, returns the first element:
+  #
+  #   a = [:foo, 'bar', 2]
+  #   a.first # => :foo
+  #   a # => [:foo, "bar", 2]
+  #
+  # If +self+ is empty, returns +nil+.
+  #
+  # When non-negative \Integer argument +n+ is given,
+  # returns the first +n+ elements in a new \Array:
+  #
+  #   a = [:foo, 'bar', 2]
+  #   a.first(2) # => [:foo, "bar"]
+  #
+  # If <tt>n >= array.size</tt>, returns all elements:
+  #
+  #   a = [:foo, 'bar', 2]
+  #   a.first(50) # => [:foo, "bar", 2]
+  #
+  # If <tt>n == 0</tt> returns an new empty \Array:
+  #
+  #   a = [:foo, 'bar', 2]
+  #   a.first(0) # []
+  #
+  # Related: #last.
   def first n = unspecified = true
     if Primitive.mandatory_only?
       Primitive.attr! :leaf
@@ -80,6 +111,37 @@ class Array
     end
   end
 
+  # call-seq:
+  #   array.last  -> object or nil
+  #   array.last(n) -> new_array
+  #
+  # Returns elements from +self+; +self+ is not modified.
+  #
+  # When no argument is given, returns the last element:
+  #
+  #   a = [:foo, 'bar', 2]
+  #   a.last # => 2
+  #   a # => [:foo, "bar", 2]
+  #
+  # If +self+ is empty, returns +nil+.
+  #
+  # When non-negative \Integer argument +n+ is given,
+  # returns the last +n+ elements in a new \Array:
+  #
+  #   a = [:foo, 'bar', 2]
+  #   a.last(2) # => ["bar", 2]
+  #
+  # If <tt>n >= array.size</tt>, returns all elements:
+  #
+  #   a = [:foo, 'bar', 2]
+  #   a.last(50) # => [:foo, "bar", 2]
+  #
+  # If <tt>n == 0</tt>, returns an new empty \Array:
+  #
+  #   a = [:foo, 'bar', 2]
+  #   a.last(0) # []
+  #
+  # Related: #first.
   def last n = unspecified = true
     if Primitive.mandatory_only?
       Primitive.attr! :leaf