Re: [doc-patch] Another rdoc formatting error in array.c
From:
"H.Yamamoto" <ocean@...2.ccsnet.ne.jp>
Date:
2004-07-13 02:59:11 UTC
List:
ruby-core #3178
Hello.
>- used 'index' as parameter name systematically
> (instead of 'i' and 'int' ...)
>- used "#" to denote method names instead of "." (as in Array#each)
>- used "array" systematically for the receiver in the
> call-seq of a method (instead of "self" sometimes earlier)
Yes, that's I intended. I understand Array.each means Arrays's class method.
"each" is instance method, so Array#each is correct.
>- used "self" for the receiver in the text describing a method
>- misc.
I used "self" but I'm not sure this should be consistent.
>- sometimes "arr" is used instead of "array"
>- sometimes methods are written as "Array#at" and sometimes as
> "<code>Array#each</code>".
I've fixed.
.....
Both _self_ and <i>self</i> appears in array.c. Is there any recomendation which
one is prefered?
.....
I realized these when I generated html from array.c.
* Array#<=> is not correctly hyper-linked. ("Array" part is hyper-linked to "Array" class)
* I think it'll be nice if other class's method `Enumerable#sort_by' is hyper-linked too.
////////////////////////
// current patch
Index: array.c
===================================================================
RCS file: /var/cvs/src/ruby/array.c,v
retrieving revision 1.151
diff -u -w -b -p -r1.151 array.c
--- array.c 9 Jul 2004 13:37:55 -0000 1.151
+++ array.c 13 Jul 2004 01:34:53 -0000
@@ -315,7 +315,7 @@ static VALUE rb_ary_replace _((VALUE, VA
* call-seq:
* Array.new(size=0, obj=nil)
* Array.new(array)
- * Array.new(size) {|i| ...}
+ * Array.new(size) {|index| block }
* Returns a new array. In the first form, the new array is
* empty. In the second it is created with _size_ copies of _obj_
@@ -762,15 +762,15 @@ rb_ary_subseq(ary, beg, len)
/*
* call-seq:
- * array[int] => obj or nil
+ * array[index] => obj or nil
* array[start, length] => an_array or nil
* array[range] => an_array or nil
- * array.slice(int) => obj or nil
+ * array.slice(index) => obj or nil
* array.slice(start, length) => an_array or nil
* array.slice(range) => an_array or nil
*
- * Element Reference---Returns the element at index _int_,
- * or returns a subarray starting at index _start_ and
+ * Element Reference---Returns the element at _index_,
+ * or returns a subarray starting at _start_ and
* continuing for _length_ elements, or returns a subarray
* specified by _range_.
* Negative indices count backward from the end of the
@@ -839,12 +839,12 @@ rb_ary_aref(argc, argv, ary)
/*
* call-seq:
- * array.at(int) #=> obj or nil
+ * array.at(index) => obj or nil
*
- * Returns the element at index int. A
+ * 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.[].
- * (Array.at is slightly faster than Array.[], as it
+ * if the index is out of range. See also Array#[].
+ * (Array#at is slightly faster than Array#[], as it
* does not accept ranges and so on.)
*
* a = [ "a", "b", "c", "d", "e" ]
@@ -919,7 +919,7 @@ rb_ary_last(argc, argv, ary)
* call-seq:
* array.fetch(index) => obj
* array.fetch(index, default ) => obj
- * array.fetch(index) {|i| block } => obj
+ * array.fetch(index) {|index| block } => obj
*
* Tries to return the element at position <i>index</i>. If the index
* lies outside the array, the first form throws an
@@ -996,7 +996,7 @@ rb_ary_index(ary, val)
* call-seq:
* array.rindex(obj) => int or nil
*
- * Returns the index of the last object in <i>arr</i>
+ * Returns the index of the last object in <i>array</i>
* <code>==</code> to <i>obj</i>. Returns <code>nil</code> if
* no match is found.
*
@@ -1099,30 +1099,30 @@ rb_ary_update(ary, beg, len, rpl)
/*
* call-seq:
- * array[int] = obj => obj
- * array[start, length] = an_array => an_array
- * array[range] = an_array => an_array
+ * array[index] = obj => obj
+ * array[start, length] = obj or an_array or nil => obj or an_array or nil
+ * array[range] = obj or an_array or nil => obj or an_array or nil
*
- * Element Assignment---Sets the element at index _int_,
- * or replaces a subarray starting at index _start_ and
+ * 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 _int_ is greater than
+ * specified by _range_. If indices are greater than
* the current capacity of the array, the array grows
- * automatically. A negative _int_ will count backward
+ * automatically. A negative indices will count backward
* from the end of the array. Inserts elements if _length_ is
- * zero. If _an_array is +nil+, deletes elements from _self_.
- * An +IndexError+ is raised if a
+ * zero. If +nil+ is used in the second and third form,
+ * deletes elements from _self_. An +IndexError+ is raised if a
* negative index points past the beginning of the array. See also
- * Array.push, and Array.unshift.
+ * <code>Array#push</code>, and <code>Array#unshift</code>.
*
* a = Array.new
- * a[4] = "4";
- * a[0, 3] = [ 'a', 'b', 'c' ]
- * a[1..2] = [ 1, 2 ];
- * a[0, 2] = "?";
- * a[0..2] = "A";
- * a[-1] = "Z";
- * a[1..-1] = nil;
+ * a[4] = "4"; #=> [nil, nil, nil, nil, "4"]
+ * a[0, 3] = [ 'a', 'b', 'c' ] #=> ["a", "b", "c", nil, "4"]
+ * a[1..2] = [ 1, 2 ] #=> ["a", 1, 2, nil, "4"]
+ * a[0, 2] = "?" #=> ["?", 2, nil, "4"]
+ * a[0..2] = "A" #=> ["A", "4"]
+ * a[-1] = "Z" #=> ["A", "Z"]
+ * a[1..-1] = nil #=> ["A"]
*/
static VALUE
@@ -1743,8 +1743,8 @@ rb_ary_sort(ary)
/*
* call-seq:
- * array.collect {|obj| block } -> an_array
- * array.map {|obj| block } -> an_array
+ * array.collect {|item| block } -> an_array
+ * array.map {|item| block } -> an_array
*
* Invokes <i>block</i> once for each element of <i>self</i>. Creates a
* new array containing the values returned by the block.
@@ -1775,12 +1775,12 @@ rb_ary_collect(ary)
/*
* call-seq:
- * array.collect! {|obj} ...} => array
- * array.map! {|obj} ...} => array
+ * array.collect! {|item| block } => array
+ * array.map! {|item| block } => array
*
- * Invokes the block once for each element of _self_self, replacing the
+ * Invokes the block once for each element of _self_, replacing the
* element with the value returned by _block_.
- * See also Enumerable.collect.
+ * See also <code>Enumerable#collect</code>.
*
* a = [ "a", "b", "c", "d" ]
* a.collect! {|x| x + "!" }
@@ -1840,7 +1840,7 @@ rb_get_values_at(obj, olen, argc, argv,
* Returns an array containing the elements in
* _self_ corresponding to the given selector(s). The selectors
* may be either integer indices or ranges.
- * See also <code>.select</code>.
+ * See also <code>Array#select</code>.
*
* a = %w{ a b c d e f }
* a.values_at(1, 3, 5)
@@ -1860,9 +1860,9 @@ rb_ary_values_at(argc, argv, ary)
/*
* call-seq:
- * array.select {|i| block } -> an_array
+ * array.select {|item| block } -> an_array
*
- * Invokes the block passing in successive elements from <i>arr</i>,
+ * Invokes the block passing in successive elements from <i>array</i>,
* returning an array containing those elements for which the block
* returns a true value (equivalent to <code>Enumerable#select</code>).
*
@@ -1889,7 +1889,7 @@ rb_ary_select(ary)
/*
* call-seq:
* array.delete(obj) => obj or nil
- * array.delete(obj) {| | block } => obj or nil
+ * array.delete(obj) { block } => obj or nil
*
* Deletes items from <i>self</i> that are equal to <i>obj</i>. If
* the item is not found, returns <code>nil</code>. If the optional
@@ -1982,7 +1982,7 @@ rb_ary_delete_at_m(ary, pos)
/*
* call-seq:
- * array.slice!(int) => obj or nil
+ * array.slice!(index) => obj or nil
* array.slice!(start, length) => sub_array or nil
* array.slice!(range) => sub_array or nil
*
@@ -2036,7 +2036,7 @@ rb_ary_slice_bang(argc, argv, ary)
/*
* call-seq:
- * array.reject! {| | block } -> array or nil
+ * array.reject! {|item| block } -> array or nil
*
* Equivalent to <code>Array#delete_if</code>, deleting elements from
* _self_ for which the block evaluates to true, but returns
@@ -2066,7 +2066,7 @@ rb_ary_reject_bang(ary)
/*
* call-seq:
- * arr.reject {|item| block } -> an_array
+ * array.reject {|item| block } -> an_array
*
* Returns a new array containing the items in _self_
* for which the block is not true.
@@ -2107,9 +2107,9 @@ rb_ary_delete_if(ary)
*
* Converts any arguments to arrays, then merges elements of
* <i>self</i> with corresponding elements from each argument. This
- * generates a sequence of <code>self#size</code> <em>n</em>-element
+ * generates a sequence of <code>self.size</code> <em>n</em>-element
* arrays, where <em>n</em> is one more that the count of arguments. If
- * the size of any argument is less than <code>enumObj#size</code>,
+ * the size of any argument is less than <code>self.size</code>,
* <code>nil</code> values are supplied. If a block given, it is
* invoked for each output array, otherwise an array of arrays is
* returned.
@@ -2234,6 +2234,7 @@ rb_ary_replace(copy, orig)
/*
* call-seq:
* array.clear => array
+ *
* Removes all elements from _self_.
*
* a = [ "a", "b", "c", "d", "e" ]
@@ -2255,17 +2256,17 @@ rb_ary_clear(ary)
/*
* call-seq:
- * array.fill(obj) -> array
+ * array.fill(obj) => array
* array.fill(obj, start [, length]) => array
* array.fill(obj, range ) => array
- * array.fill {|i| block } => array
- * array.fill(start [, length] ) {|i| block } => array
- * array.fill(range) {|i| block } => array
+ * array.fill {|index| block } => array
+ * array.fill(start [, length] ) {|index| block } => array
+ * array.fill(range) {|index| block } => array
*
* The first three forms set the selected elements of <i>self</i> (which
* may be the entire array) to <i>obj</i>. A <i>start</i> of
* <code>nil</code> is equivalent to zero. A <i>length</i> of
- * <code>nil</code> is equivalent to <i>arr</i>.length. The last three
+ * <code>nil</code> is equivalent to <i>self.length</i>. The last three
* forms fill the array with the value of the block. The block is
* passed the absolute index of each element to be filled.
*
@@ -2376,7 +2377,7 @@ rb_ary_plus(x, y)
/*
* call-seq:
- * self.concat(other_array) => array
+ * array.concat(other_array) => array
*
* Appends the elements in other_array to _self_.
*
@@ -2407,6 +2408,7 @@ rb_ary_concat(x, y)
*
*
* [ 1, 2, 3 ] * 3 #=> [ 1, 2, 3, 1, 2, 3, 1, 2, 3 ]
+ * [ 1, 2, 3 ] * "-" #=> "1-2-3"
*
*/
@@ -2453,7 +2455,7 @@ rb_ary_times(ary, times)
* Returns the first contained array that matches (that
* is, the first associated array),
* or +nil+ if no match is found.
- * See also Array.rassoc.
+ * See also <code>Array#rassoc</code>.
*
* s1 = [ "colors", "red", "blue", "green" ]
* s2 = [ "letters", "a", "b", "c" ]
@@ -2638,7 +2640,7 @@ rb_ary_includes(ary, item)
* equal, then that inequality is the return value. If all the
* values found are equal, then the return is based on a
* comparison of the array lengths. Thus, two arrays are
- * ``equal'' according to Array.<=> if and only if they have
+ * ``equal'' according to <code>Array#<=></code> if and only if they have
* the same length and the value of each element is equal to the
* value of the corresponding element in the other array.
*
@@ -2854,7 +2856,7 @@ rb_ary_uniq(ary)
* array.compact! => array or nil
*
* Removes +nil+ elements from array.
- * Returns +niL+ if no changes were made.
+ * Returns +nil+ if no changes were made.
* [ "a", nil, "b", nil, "c" ].compact! #=> [ "a", "b", "c" ]
* [ "a", "b", "c" ].compact! #=> nil
*/
@@ -2958,11 +2960,11 @@ flatten(ary, idx, ary2, memo)
/*
* call-seq:
- * arr.flatten! -> arr or nil
+ * array.flatten! -> array or nil
*
* Flattens _self_ in place.
* Returns <code>nil</code> if no modifications were made (i.e.,
- * <i>arr</i> contains no subarrays.)
+ * <i>array</i> contains no subarrays.)
*
* a = [ 1, 2, [3, [4, 5] ] ]
* a.flatten! #=> [1, 2, 3, 4, 5]