[前][次][番号順一覧][スレッド一覧]

ruby-changes:23807

From: drbrain <ko1@a...>
Date: Fri, 1 Jun 2012 08:51:43 +0900 (JST)
Subject: [ruby-changes:23807] drbrain:r35858 (trunk): * array.c: Updated Array documentation formatting. Patch by Zachary

drbrain	2012-06-01 08:51:33 +0900 (Fri, 01 Jun 2012)

  New Revision: 35858

  http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=35858

  Log:
    * array.c:  Updated Array documentation formatting.  Patch by Zachary
      Scott.  [ruby-trunk - Feature #6517]

  Modified files:
    trunk/ChangeLog
    trunk/array.c

Index: array.c
===================================================================
--- array.c	(revision 35857)
+++ array.c	(revision 35858)
@@ -274,6 +274,16 @@
     }
 }
 
+/*
+ *  call-seq:
+ *      ary.freeze -> ary
+ *
+ *  Calls Object#freeze on +ary+ to prevent any further
+ *  modification. A RuntimeError will be raised if a modification
+ *  attempt is made.
+ *
+ */
+
 VALUE
 rb_ary_freeze(VALUE ary)
 {
@@ -284,8 +294,8 @@
  *  call-seq:
  *     ary.frozen?  -> true or false
  *
- *  Return <code>true</code> if this array is frozen (or temporarily frozen
- *  while being sorted).
+ *  Return +true+ if this array is frozen (or temporarily frozen
+ *  while being sorted). See also Object#frozen?
  */
 
 static VALUE
@@ -772,13 +782,16 @@
  *  call-seq:
  *     ary.push(obj, ... )   -> ary
  *
- *  Append---Pushes the given object(s) on to the end of this array. This
+ *  Append --- Pushes the given object(s) on to the end of this array. This
  *  expression returns the array itself, so several appends
- *  may be chained together.
+ *  may be chained together. See also Array#pop for the opposite
+ *  effect.
  *
  *     a = [ "a", "b", "c" ]
  *     a.push("d", "e", "f")
  *             #=> ["a", "b", "c", "d", "e", "f"]
+ *     [1, 2, 3,].push(4).push(5)
+ *             #=> [1, 2, 3, 4, 5]
  */
 
 static VALUE
@@ -810,10 +823,11 @@
  *     ary.pop(n) -> new_ary
  *
  *  Removes the last element from +self+ and returns it, or
- *  <code>nil</code> if the array is empty.
+ *  +nil+ if the array is empty.
  *
- *  If a number +n+ is given, returns an array of the last n elements
- *  (or less) just like <code>array.slice!(-n, n)</code> does.
+ *  If a number +n+ is given, returns an array of the last +n+ elements
+ *  (or less) just like <code>array.slice!(-n, n)</code> does. See also
+ *  Array#push for the opposite effect.
  *
  *     a = [ "a", "b", "c", "d" ]
  *     a.pop     #=> "d"
@@ -869,12 +883,14 @@
  *     ary.shift    -> obj or nil
  *     ary.shift(n) -> new_ary
  *
- *  Returns the first element of +self+ and removes it (shifting all
- *  other elements down by one). Returns <code>nil</code> if the array
+ *  Removes the first element of +self+ and returns it (shifting all
+ *  other elements down by one). Returns +nil+ if the array
  *  is empty.
  *
- *  If a number +n+ is given, returns an array of the first n elements
- *  (or less) just like <code>array.slice!(0, n)</code> does.
+ *  If a number +n+ is given, returns an array of the first +n+ elements
+ *  (or less) just like <code>array.slice!(0, n)</code> does. With +ary+
+ *  containing only the remainder elements, not including what was shifted to
+ *  +new_ary+. See also Array#unshift for the opposite effect.
  *
  *     args = [ "-m", "-q", "filename" ]
  *     args.shift     #=> "-m"
@@ -916,8 +932,8 @@
  *  call-seq:
  *     ary.unshift(obj, ...)  -> ary
  *
- *  Prepends objects to the front of +self+,
- *  moving other elements upwards.
+ *  Prepends objects to the front of +self+, moving other elements upwards.
+ *  See also Array#shift for the opposite effect.
  *
  *     a = [ "b", "c", "d" ]
  *     a.unshift("a")   #=> ["a", "b", "c", "d"]
@@ -1056,9 +1072,9 @@
  *  call-seq:
  *     ary.at(index)   ->   obj  or nil
  *
- *  Returns the element at +index+. A
- *  negative index counts from the end of +self+.  Returns +nil+
- *  if the index is out of range. See also <code>Array#[]</code>.
+ *  Returns the element at +index+. A negative index counts from the end of
+ *  +self+. Returns +nil+ if the index is out of range. See also
+ *  Array#[].
  *
  *     a = [ "a", "b", "c", "d", "e" ]
  *     a.at(0)     #=> "a"
@@ -1077,8 +1093,9 @@
  *     ary.first(n)  ->   new_ary
  *
  *  Returns the first element, or the first +n+ elements, of the array.
- *  If the array is empty, the first form returns <code>nil</code>, and the
- *  second form returns an empty array.
+ *  If the array is empty, the first form returns +nil+, and the
+ *  second form returns an empty array. See also Array#last for
+ *  the opposite effect.
  *
  *     a = [ "q", "r", "s", "t" ]
  *     a.first     #=> "q"
@@ -1103,8 +1120,10 @@
  *     ary.last(n)  ->  new_ary
  *
  *  Returns the last element(s) of +self+. If the array is empty,
- *  the first form returns <code>nil</code>.
+ *  the first form returns +nil+.
  *
+ *  See also Array#first for the opposite effect.
+ *
  *     a = [ "w", "x", "y", "z" ]
  *     a.last     #=> "z"
  *     a.last(2)  #=> ["y", "z"]
@@ -1125,22 +1144,18 @@
 /*
  *  call-seq:
  *     ary.fetch(index)                    -> obj
- *     ary.fetch(index, default )          -> obj
- *     ary.fetch(index) {|index| block }   -> obj
+ *     ary.fetch(index, default)           -> obj
+ *     ary.fetch(index) { |index| block }  -> obj
  *
- *  Tries to return the element at position +index+. If the index lies outside
- *  the array, the first form throws an IndexError exception, the second form
- *  returns +default+, and the third form returns the value of invoking the
- *  block, passing in the index. Negative values of +index+ count from the end
- *  of the array.
- *
  *  Tries to return the element at position +index+, but throws an IndexError
- *  exception if the referenced index lies outside of the array bounds.  This
+ *  exception if the referenced +index+ lies outside of the array bounds.  This
  *  error can be prevented by supplying a second argument, which will act as a
- *  +default+ value.  Alternatively, if the second argument is a block it will
- *  only be executed when an invalid index is referenced.  Negative values of
- *  +index+ count from the end of the array.
+ *  +default+ value.
  *
+ *  Alternatively, if a block is given it will only be executed when an
+ *  invalid +index+ is referenced.  Negative values of +index+ count from the
+ *  end of the array.
+ *
  *     a = [ 11, 22, 33, 44 ]
  *     a.fetch(1)               #=> 22
  *     a.fetch(-1)              #=> 44
@@ -1179,24 +1194,27 @@
 
 /*
  *  call-seq:
- *     ary.index(obj)           ->  int or nil
- *     ary.index {|item| block} ->  int or nil
- *     ary.index                ->  an_enumerator
+ *     ary.index(obj)             ->  int or nil
+ *     ary.index { |item| block } ->  int or nil
+ *     ary.index                  ->  Enumerator
  *
- *  Returns the index of the first object in +self+ such that the object is
- *  <code>==</code> to +obj+. If a block is given instead of an
- *  argument, returns index of first object for which <em>block</em> is true.
- *  Returns <code>nil</code> if no match is found.
- *  See also <code>Array#rindex</code>.
+ *  Returns the _index_ of the first object in +ary+ such that the object is
+ *  <code>==</code> to +obj+.
  *
- *  If neither block nor argument is given, an enumerator is returned instead.
+ *  If a block is given instead of an argument, returns the _index_ of first
+ *  the object for which the block returns +true+.  Returns +nil+ if no match
+ *  is found.
  *
+ *  See also Array#rindex.
+ *
+ *  An Enumerator is returned if neither a block nor argument is given.
+ *
  *     a = [ "a", "b", "c" ]
- *     a.index("b")        #=> 1
- *     a.index("z")        #=> nil
- *     a.index{|x|x=="b"}  #=> 1
+ *     a.index("b")              #=> 1
+ *     a.index("z")              #=> nil
+ *     a.index { |x| x == "b" }  #=> 1
  *
- *  This is an alias of <code>#find_index</code>.
+ *  This is an alias of Array#find_index.
  */
 
 static VALUE
@@ -1226,18 +1244,20 @@
 
 /*
  *  call-seq:
- *     ary.rindex(obj)           ->  int or nil
- *     ary.rindex {|item| block} ->  int or nil
- *     ary.rindex                ->  an_enumerator
+ *     ary.rindex(obj)             ->  int or nil
+ *     ary.rindex { |item| block } ->  int or nil
+ *     ary.rindex                  ->  Enumerator
  *
- *  Returns the index of the last object in +self+
- *  <code>==</code> to +obj+. If a block is given instead of an
- *  argument, returns index of first object for which <em>block</em> is
- *  true, starting from the last object.
- *  Returns <code>nil</code> if no match is found.
+ *  Returns the _index_ of the last object in +self+ <code>==</code> to +obj+.
+ *
+ *  If a block is given instead of an argument, returns _index_ of first object
+ *  for which block returns +true+, starting from the last object.
+ *
+ *  Returns +nil+ if no match is found.
+ *
  *  See also Array#index.
  *
- *  If neither block nor argument is given, an enumerator is returned instead.
+ *  If neither block nor argument is given, an Enumerator is returned instead.
  *
  *     a = [ "a", "b", "b", "b", "c" ]
  *     a.rindex("b")             #=> 3
@@ -1409,17 +1429,19 @@
  *     ary[start, length] = obj or other_ary or nil  ->  obj or other_ary or nil
  *     ary[range]         = obj or other_ary or nil  ->  obj or other_ary or nil
  *
- *  Element Assignment---Sets the element at +index+,
- *  or replaces a subarray starting at +start+ and
- *  continuing for +length+ elements, or replaces a subarray
- *  specified by +range+.  If indices are greater than
- *  the current capacity of the array, the array grows
- *  automatically. A negative indices will count backward
- *  from the end of the array. Inserts elements if +length+ is
- *  zero. An IndexError is raised if a negative index points
- *  past the beginning of the array. See also
- *  Array#push, and Array#unshift.
+ *  Element Assignment --- Sets the element at +index+, or replaces a subarray
+ *  from +start+ for +length+ elements, or replaces a subarray specified by
+ *  +range+.
  *
+ *  If indices are greater than the current capacity of the array, the array
+ *  grows automatically. Negative indices will count backward from the end of
+ *  the array. Inserts elements if +length+ is zero.
+ *
+ *  An IndexError is raised if a negative index points past the beginning of
+ *  the array.
+ *
+ *  See also Array#push, and Array#unshift.
+ *
  *     a = Array.new
  *     a[4] = "4";                 #=> [nil, nil, nil, nil, "4"]
  *     a[0, 3] = [ 'a', 'b', 'c' ] #=> ["a", "b", "c", nil, "4"]
@@ -1465,9 +1487,11 @@
  *  call-seq:
  *     ary.insert(index, obj...)  -> ary
  *
- *  Inserts the given values before the element with the given index
- *  (which may be negative).
+ *  Inserts the given values before the element with the given +index+.
  *
+ *  Negative indices count backwards from the end of the array, where +-1+ is
+ *  the last element.
+ *
  *     a = %w{ a b c d }
  *     a.insert(2, 99)         #=> ["a", "b", 99, "c", "d"]
  *     a.insert(-2, 1, 2, 3)   #=> ["a", "b", 99, "c", 1, 2, 3, "d"]
@@ -1494,13 +1518,13 @@
 
 /*
  *  call-seq:
- *     ary.each {|item| block }   -> ary
- *     ary.each                   -> an_enumerator
+ *     ary.each { |item| block }  -> ary
+ *     ary.each                   -> Enumerator
  *
- *  Calls +block+ once for each element in +self+, passing that
- *  element as a parameter.
+ *  Calls the given block once for each element in +self+, passing that element
+ *  as a parameter.
  *
- *  If no block is given, an enumerator is returned instead.
+ *  An Enumerator is returned if no block is given.
  *
  *     a = [ "a", "b", "c" ]
  *     a.each {|x| print x, " -- " }
@@ -1525,15 +1549,14 @@
 
 /*
  *  call-seq:
- *     ary.each_index {|index| block }  -> ary
- *     ary.each_index                   -> an_enumerator
+ *     ary.each_index { |index| block }  -> ary
+ *     ary.each_index                    -> Enumerator
  *
- *  Same as Array#each, but passes the index of the element instead of the
+ *  Same as Array#each, but passes the +index+ of the element instead of the
  *  element itself.
  *
- *  If no block is given, an enumerator is returned instead.
+ *  An Enumerator is returned if no block is given.
  *
- *
  *     a = [ "a", "b", "c" ]
  *     a.each_index {|x| print x, " -- " }
  *
@@ -1556,8 +1579,8 @@
 
 /*
  *  call-seq:
- *     ary.reverse_each {|item| block }   -> ary
- *     ary.reverse_each                   -> an_enumerator
+ *     ary.reverse_each { |item| block }  -> ary
+ *     ary.reverse_each                   -> Enumerator
  *
  *  Same as Array#each, but traverses +self+ in reverse order.
  *
@@ -1592,6 +1615,7 @@
  *  Returns the number of elements in +self+. May be zero.
  *
  *     [ 1, 2, 3, 4, 5 ].length   #=> 5
+ *     [].length                  #=> 0
  */
 
 static VALUE
@@ -1605,7 +1629,7 @@
  *  call-seq:
  *     ary.empty?   -> true or false
  *
- *  Returns <code>true</code> if +self+ contains no elements.
+ *  Returns +true+ if +self+ contains no elements.
  *
  *     [].empty?   #=> true
  */
@@ -1771,10 +1795,10 @@
 
 /*
  *  call-seq:
- *     ary.join(sep=$,)    -> str
+ *     ary.join(separator=$,)    -> str
  *
  *  Returns a string created by converting each element of the array to
- *  a string, separated by +sep+.
+ *  a string, separated by the given +separator+.
  *
  *     [ "a", "b", "c" ].join        #=> "abc"
  *     [ "a", "b", "c" ].join("-")   #=> "a-b-c"
@@ -1817,10 +1841,12 @@
 
 /*
  *  call-seq:
- *     ary.to_s -> string
  *     ary.inspect  -> string
+ *     ary.to_s     -> string
  *
  *  Creates a string representation of +self+.
+ *
+ *     [ "a", "b", "c" ].to_s     #=> "[\"a\", \"b\", \"c\"]"
  */
 
 static VALUE
@@ -1840,8 +1866,9 @@
  *  call-seq:
  *     ary.to_a     -> ary
  *
- *  Returns +self+. If called on a subclass of Array, converts
- *  the receiver to an Array object.
+ *  Returns +self+.
+ *
+ *  If called on a subclass of Array, converts the receiver to an Array object.
  */
 
 static VALUE
@@ -1912,7 +1939,7 @@
 
 /*
  *  call-seq:
- *     ary.reverse -> new_ary
+ *     ary.reverse    -> new_ary
  *
  *  Returns a new array containing +self+'s elements in reverse order.
  *
@@ -1964,12 +1991,14 @@
 
 /*
  *  call-seq:
- *     ary.rotate!(cnt=1) -> ary
+ *     ary.rotate!(count=1)   -> ary
  *
- *  Rotates +self+ in place so that the element at +cnt+ comes first,
- *  and returns +self+.  If +cnt+ is negative then it rotates in
- *  the opposite direction.
+ *  Rotates +self+ in place so that the element at +count+ comes first, and
+ *  returns +self+.
  *
+ *  If +count+ is negative then it rotates in the opposite direction, starting
+ *  from the end of the array where +-1+ is the last element.
+ *
  *     a = [ "a", "b", "c", "d" ]
  *     a.rotate!        #=> ["b", "c", "d", "a"]
  *     a                #=> ["b", "c", "d", "a"]
@@ -1993,12 +2022,14 @@
 
 /*
  *  call-seq:
- *     ary.rotate(cnt=1) -> new_ary
+ *     ary.rotate(count=1)    -> new_ary
  *
- *  Returns new array by rotating +self+ so that the element at
- *  +cnt+ in +self+ is the first element of the new array. If +cnt+
- *  is negative then it rotates in the opposite direction.
+ *  Returns new array by rotating +self+ so that the element at +count+ is the
+ *  first element of the new array.
  *
+ *  If +count+ is negative then it rotates in the opposite direction, starting
+ *  from the end of +self+ where +-1+ is the last element.
+ *
  *     a = [ "a", "b", "c", "d" ]
  *     a.rotate         #=> ["b", "c", "d", "a"]
  *     a                #=> ["a", "b", "c", "d"]
@@ -2104,17 +2135,22 @@
 /*
  *  call-seq:
  *     ary.sort!                   -> ary
- *     ary.sort! {| a,b | block }  -> ary
+ *     ary.sort! { |a, b| block }  -> ary
  *
- *  Sorts +self+. Comparisons for
- *  the sort will be done using the <code><=></code> operator or using
- *  an optional code block. The block implements a comparison between
- *  +a+ and +b+, returning -1, 0, or +1. See also
- *  Enumerable#sort_by.
+ *  Sorts +self+ in place.
  *
+ *  Comparisons for the sort will be done using the <code><=></code> operator
+ *  or using an optional code block.
+ *
+ *  The block must implement a comparison between +a+ and +b+, and return
+ *  +-1+, when +a+ follows +b+, +0+ when +a+ and +b+ are equivalent, or ++1+
+ *  if +b+ follows +a+.
+ *
+ *  See also Enumerable#sort_by.
+ *
  *     a = [ "d", "a", "e", "c", "b" ]
  *     a.sort!                    #=> ["a", "b", "c", "d", "e"]
- *     a.sort! {|x,y| y <=> x }   #=> ["e", "d", "c", "b", "a"]
+ *     a.sort! { |x,y| y <=> x }  #=> ["e", "d", "c", "b", "a"]
  */
 
 VALUE
@@ -2180,17 +2216,23 @@
 /*
  *  call-seq:
  *     ary.sort                   -> new_ary
- *     ary.sort {| a,b | block }  -> new_ary
+ *     ary.sort { |a, b| block }  -> new_ary
  *
- *  Returns a new array created by sorting +self+. Comparisons for
- *  the sort will be done using the <code><=></code> operator or using
- *  an optional code block. The block implements a comparison between
- *  +a+ and +b+, returning -1, 0, or +1. See also
- *  Enumerable#sort_by.
+ *  Returns a new array created by sorting +self+.
  *
+ *  Comparisons for the sort will be done using the <code><=></code> operator
+ *  or using an optional code block.
+ *
+ *  The block must implement a comparison between +a+ and +b+, and return
+ *  +-1+, when +a+ follows +b+, +0+ when +a+ and +b+ are equivalent, or ++1+
+ *  if +b+ follows +a+.
+ *
+ *
+ *  See also Enumerable#sort_by.
+ *
  *     a = [ "d", "a", "e", "c", "b" ]
  *     a.sort                    #=> ["a", "b", "c", "d", "e"]
- *     a.sort {|x,y| y <=> x }   #=> ["e", "d", "c", "b", "a"]
+ *     a.sort { |x,y| y <=> x }  #=> ["e", "d", "c", "b", "a"]
  */
 
 VALUE
@@ -2210,13 +2252,13 @@
 
 /*
  *  call-seq:
- *     ary.sort_by! {| obj | block }    -> ary
- *     ary.sort_by!                     -> an_enumerator
+ *     ary.sort_by! { |obj| block }    -> ary
+ *     ary.sort_by!                    -> Enumerator
  *
  *  Sorts +self+ in place using a set of keys generated by mapping the
  *  values in +self+ through the given block.
  *
- *  If no block is given, an enumerator is returned instead.
+ *  If no block is given, an Enumerator is returned instead.
  *
  */
 
@@ -2235,20 +2277,22 @@
 
 /*
  *  call-seq:
- *     ary.collect {|item| block }  -> new_ary
- *     ary.map     {|item| block }  -> new_ary
- *     ary.collect                  -> an_enumerator
- *     ary.map                      -> an_enumerator
+ *     ary.collect { |item| block }  -> new_ary
+ *     ary.map     { |item| block }  -> new_ary
+ *     ary.collect                   -> Enumerator
+ *     ary.map                       -> Enumerator
  *
- *  Invokes +block+ once for each element of +self+. Creates a
- *  new array containing the values returned by the block.
+ *  Invokes the given block once for each element of +self+.
+ *
+ *  Creates a new array containing the values returned by the block.
+ *
  *  See also Enumerable#collect.
  *
- *  If no block is given, an enumerator is returned instead.
+ *  If no block is given, an Enumerator is returned instead.
  *
  *     a = [ "a", "b", "c", "d" ]
- *     a.map {|x| x + "!" }   #=> ["a!", "b!", "c!", "d!"]
- *     a                      #=> ["a", "b", "c", "d"]
+ *     a.map { |x| x + "!" }   #=> ["a!", "b!", "c!", "d!"]
+ *     a                       #=> ["a", "b", "c", "d"]
  */
 
 static VALUE
@@ -2270,14 +2314,15 @@
  *  call-seq:
  *     ary.collect! {|item| block }   -> ary
  *     ary.map!     {|item| block }   -> ary
- *     ary.collect                    -> an_enumerator
- *     ary.map                        -> an_enumerator
+ *     ary.collect!                   -> Enumerator
+ *     ary.map!                       -> Enumerator
  *
- *  Invokes the block once for each element of +self+, replacing the
- *  element with the value returned by +block+.
+ *  Invokes the given block once for each element of +self+, replacing the
+ *  element with the value returned by the block.
+ *
  *  See also Enumerable#collect.
  *
- *  If no block is given, an enumerator is returned instead.
+ *  If no block is given, an Enumerator is returned instead.
  *
  *     a = [ "a", "b", "c", "d" ]
  *     a.map! {|x| x + "!" }
@@ -2327,11 +2372,13 @@
 
 /*
  *  call-seq:
- *     ary.values_at(selector,... )  -> new_ary
+ *   (... truncated)

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/

[前][次][番号順一覧][スレッド一覧]