ruby-changes:21373
From: drbrain <ko1@a...>
Date: Fri, 7 Oct 2011 07:03:05 +0900 (JST)
Subject: [ruby-changes:21373] drbrain:r33422 (trunk): * array.c: Use + for arguments described in documentation to allow
drbrain 2011-10-07 06:36:17 +0900 (Fri, 07 Oct 2011) New Revision: 33422 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=33422 Log: * array.c: Use + for arguments described in documentation to allow rdoc -C2 to work better. Remove <code> from method references to allow cross-references in HTML documentation. Modified files: trunk/ChangeLog trunk/array.c Index: array.c =================================================================== --- array.c (revision 33421) +++ array.c (revision 33422) @@ -478,8 +478,8 @@ * call-seq: * Array.try_convert(obj) -> array or nil * - * Try to convert <i>obj</i> into an array, using +to_ary+ method. - * Returns converted array or +nil+ if <i>obj</i> cannot be converted + * Try to convert +obj+ into an array, using +to_ary+ method. + * Returns converted array or +nil+ if +obj+ cannot be converted * for any reason. This method can be used to check if an argument is an * array. * @@ -506,14 +506,12 @@ * Array.new(array) * Array.new(size) {|index| block } * - * Returns a new array. In the first form, the new array is - * empty, or it is created with _size_ copies of _obj_ (that is, - * _size_ references to the same _obj_). - * The second form creates a copy of the array - * passed as a parameter (the array is generated by calling - * to_ary on the parameter). In the last form, an array - * of the given size is created. Each element in this array is - * calculated by passing the element's index to the given block and + * Returns a new array. In the first form, the new array is empty, or it is + * created with +size+ copies of +obj+ (that is, +size+ references to the + * same +obj+). The second form creates a copy of the array passed as a + * parameter (the array is generated by calling to_ary on the parameter). In + * the last form, an array of the given size is created. Each element in this + * array is calculated by passing the element's index to the given block and * storing the return value. * * Array.new # => [] (empty array) @@ -787,7 +785,7 @@ * Removes the last element from +self+ and returns it, or * <code>nil</code> if the array is empty. * - * If a number _n_ is given, returns an array of the last n elements + * 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. * * a = [ "a", "b", "c", "d" ] @@ -848,7 +846,7 @@ * other elements down by one). Returns <code>nil</code> if the array * is empty. * - * If a number _n_ is given, returns an array of the first n elements + * 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. * * args = [ "-m", "-q", "filename" ] @@ -970,10 +968,10 @@ * ary.slice(start, length) -> new_ary or nil * ary.slice(range) -> new_ary or nil * - * 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_. + * 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 * array (-1 is the last element). Returns +nil+ if the index * (or starting index) are out of range. @@ -1031,7 +1029,7 @@ * call-seq: * ary.at(index) -> obj or nil * - * Returns the element at _index_. 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 <code>Array#[]</code>. * @@ -1103,12 +1101,11 @@ * ary.fetch(index, default ) -> obj * ary.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 - * <code>IndexError</code> exception, the second form returns - * <i>default</i>, and the third form returns the value of invoking - * the block, passing in the index. Negative values of <i>index</i> - * count from the end of the array. + * 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. * * a = [ 11, 22, 33, 44 ] * a.fetch(1) #=> 22 @@ -1152,7 +1149,7 @@ * ary.index -> an_enumerator * * Returns the index of the first object in +self+ such that the object is - * <code>==</code> to <i>obj</i>. If a block is given instead of an + * <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>. @@ -1199,11 +1196,11 @@ * ary.rindex -> an_enumerator * * Returns the index of the last object in +self+ - * <code>==</code> to <i>obj</i>. If a block is given instead of an + * <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. - * See also <code>Array#index</code>. + * See also Array#index. * * If neither block nor argument is given, an enumerator is returned instead. * @@ -1377,16 +1374,16 @@ * 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 + * 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 + * 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 - * <code>Array#push</code>, and <code>Array#unshift</code>. + * Array#push, and Array#unshift. * * a = Array.new * a[4] = "4"; #=> [nil, nil, nil, nil, "4"] @@ -1469,7 +1466,7 @@ * ary.each {|item| block } -> ary * ary.each -> an_enumerator * - * Calls <i>block</i> once for each element in +self+, passing that + * Calls +block+ once for each element in +self+, passing that * element as a parameter. * * If no block is given, an enumerator is returned instead. @@ -1500,8 +1497,8 @@ * ary.each_index {|index| block } -> ary * ary.each_index -> an_enumerator * - * Same as <code>Array#each</code>, but passes the index of the element - * instead of the element itself. + * 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. * @@ -1531,8 +1528,7 @@ * ary.reverse_each {|item| block } -> ary * ary.reverse_each -> an_enumerator * - * Same as <code>Array#each</code>, but traverses +self+ in reverse - * order. + * Same as Array#each, but traverses +self+ in reverse order. * * a = [ "a", "b", "c" ] * a.reverse_each {|x| print x, " " } @@ -1747,7 +1743,7 @@ * ary.join(sep=$,) -> str * * Returns a string created by converting each element of the array to - * a string, separated by <i>sep</i>. + * a string, separated by +sep+. * * [ "a", "b", "c" ].join #=> "abc" * [ "a", "b", "c" ].join("-") #=> "a-b-c" @@ -2082,8 +2078,8 @@ * 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 - * <i>a</i> and <i>b</i>, returning -1, 0, or +1. See also - * <code>Enumerable#sort_by</code>. + * +a+ and +b+, returning -1, 0, or +1. See also + * Enumerable#sort_by. * * a = [ "d", "a", "e", "c", "b" ] * a.sort! #=> ["a", "b", "c", "d", "e"] @@ -2158,8 +2154,8 @@ * 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 - * <i>a</i> and <i>b</i>, returning -1, 0, or +1. See also - * <code>Enumerable#sort_by</code>. + * +a+ and +b+, returning -1, 0, or +1. See also + * Enumerable#sort_by. * * a = [ "d", "a", "e", "c", "b" ] * a.sort #=> ["a", "b", "c", "d", "e"] @@ -2213,9 +2209,9 @@ * ary.collect -> an_enumerator * ary.map -> an_enumerator * - * Invokes <i>block</i> once for each element of +self+. Creates a + * Invokes +block+ once for each element of +self+. Creates a * new array containing the values returned by the block. - * See also <code>Enumerable#collect</code>. + * See also Enumerable#collect. * * If no block is given, an enumerator is returned instead. * @@ -2247,8 +2243,8 @@ * ary.map -> an_enumerator * * Invokes the block once for each element of +self+, replacing the - * element with the value returned by _block_. - * See also <code>Enumerable#collect</code>. + * element with the value returned by +block+. + * See also Enumerable#collect. * * If no block is given, an enumerator is returned instead. * @@ -2305,7 +2301,7 @@ * 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>Array#select</code>. + * See also Array#select. * * a = %w{ a b c d e f } * a.values_at(1, 3, 5) @@ -2328,7 +2324,7 @@ * * Invokes the block passing in successive elements from +self+, * returning an array containing those elements for which the block - * returns a true value (equivalent to <code>Enumerable#select</code>). + * returns a true value (equivalent to Enumerable#select). * * If no block is given, an enumerator is returned instead. * @@ -2361,7 +2357,7 @@ * +self+, deleting elements for which the block returns a * false value. It returns +self+ if changes were made, * otherwise it returns <code>nil</code>. - * See also <code>Array#keep_if</code> + * See also Array#keep_if * * If no block is given, an enumerator is returned instead. * @@ -2394,9 +2390,9 @@ * ary.keep_if {|item| block } -> ary * ary.keep_if -> an_enumerator * - * Deletes every element of +self+ for which <i>block</i> evaluates + * Deletes every element of +self+ for which +block+ evaluates * to false. - * See also <code>Array#select!</code> + * See also Array#select! * * If no block is given, an enumerator is returned instead. * @@ -2417,10 +2413,10 @@ * ary.delete(obj) -> obj or nil * ary.delete(obj) { block } -> obj or nil * - * Deletes items from +self+ that are equal to <i>obj</i>. - * If any items are found, returns <i>obj</i>. If + * Deletes items from +self+ that are equal to +obj+. + * If any items are found, returns +obj+. If * the item is not found, returns <code>nil</code>. If the optional - * code block is given, returns the result of <i>block</i> if the item + * code block is given, returns the result of +block+ if the item * is not found. (To remove <code>nil</code> elements and * get an informative return value, use #compact!) * @@ -2495,7 +2491,7 @@ * * Deletes the element at the specified index, returning that element, * or <code>nil</code> if the index is out of range. See also - * <code>Array#slice!</code>. + * Array#slice!. * * a = ["ant", "bat", "cat", "dog"] * a.delete_at(2) #=> "cat" @@ -2618,10 +2614,10 @@ * ary.reject! {|item| block } -> ary or nil * ary.reject! -> an_enumerator * - * Equivalent to <code>Array#delete_if</code>, deleting elements from + * Equivalent to Array#delete_if, deleting elements from * +self+ for which the block evaluates to true, but returns * <code>nil</code> if no changes were made. - * See also <code>Enumerable#reject</code> and <code>Array#delete_if</code>. + * See also Enumerable#reject and Array#delete_if. * * If no block is given, an enumerator is returned instead. * @@ -2641,7 +2637,7 @@ * * Returns a new array containing the items in +self+ * for which the block is not true. - * See also <code>Array#delete_if</code> + * See also Array#delete_if * * If no block is given, an enumerator is returned instead. * @@ -2663,9 +2659,9 @@ * ary.delete_if {|item| block } -> ary * ary.delete_if -> an_enumerator * - * Deletes every element of +self+ for which <i>block</i> evaluates + * Deletes every element of +self+ for which +block+ evaluates * to true. - * See also <code>Array#reject!</code> + * See also Array#reject! * * If no block is given, an enumerator is returned instead. * @@ -2801,7 +2797,7 @@ * ary.replace(other_ary) -> ary * * Replaces the contents of +self+ with the contents of - * <i>other_ary</i>, truncating or expanding if necessary. + * +other_ary+, truncating or expanding if necessary. * * a = [ "a", "b", "c", "d", "e" ] * a.replace([ "x", "y", "z" ]) #=> ["x", "y", "z"] @@ -2887,12 +2883,12 @@ * ary.fill(range) {|index| block } -> ary * * The first three forms set the selected elements of +self+ (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>self.length</i>. The last three + * may be the entire array) to +obj+. A +start+ of + * <code>nil</code> is equivalent to zero. A +length+ of + * <code>nil</code> is equivalent to <code>self.length</code>. 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. - * Negative values of <i>start</i> count from the end of the array. + * Negative values of +start+ count from the end of the array. * * a = [ "a", "b", "c", "d" ] * a.fill("x") #=> ["x", "x", "x", "x"] @@ -3002,7 +2998,7 @@ * call-seq: * ary.concat(other_ary) -> ary * - * Appends the elements of <i>other_ary</i> to +self+. + * Appends the elements of +other_ary+ to +self+. * * [ "a", "b" ].concat( ["c", "d"] ) #=> [ "a", "b", "c", "d" ] */ @@ -3027,7 +3023,7 @@ * * Repetition---With a String argument, equivalent to * self.join(str). Otherwise, returns a new array - * built by concatenating the _int_ copies of +self+. + * built by concatenating the +int+ copies of +self+. * * * [ 1, 2, 3 ] * 3 #=> [ 1, 2, 3, 1, 2, 3, 1, 2, 3 ] @@ -3086,12 +3082,12 @@ * ary.assoc(obj) -> new_ary or nil * * Searches through an array whose elements are also arrays - * comparing _obj_ with the first element of each contained array + * comparing +obj+ with the first element of each contained array * using obj.==. * Returns the first contained array that matches (that * is, the first associated array), * or +nil+ if no match is found. - * See also <code>Array#rassoc</code>. + * See also Array#rassoc. * * s1 = [ "colors", "red", "blue", "green" ] * s2 = [ "letters", "a", "b", "c" ] @@ -3121,9 +3117,9 @@ * ary.rassoc(obj) -> new_ary or nil * * Searches through the array whose elements are also arrays. Compares - * _obj_ with the second element of each contained array using + * +obj+ with the second element of each contained array using * <code>==</code>. Returns the first contained array that matches. See - * also <code>Array#assoc</code>. + * also Array#assoc. * * a = [ [ 1, "one"], [2, "two"], [3, "three"], ["ii", "two"] ] * a.rassoc("two") #=> [2, "two"] @@ -3204,7 +3200,7 @@ * call-seq: * ary.eql?(other) -> true or false * - * Returns <code>true</code> if +self+ and _other_ are the same object, + * Returns <code>true</code> if +self+ and +other+ are the same object, * or are both arrays with the same content. */ @@ -3254,10 +3250,10 @@ /* * call-seq: - * ary.include?(obj) -> true or false + * ary.include?(object) -> true or false * - * Returns <code>true</code> if the given object is present in - * +self+ (that is, if any object <code>==</code> <i>anObject</i>), + * Returns <code>true</code> if the given +object+ is present in + * +self+ (that is, if any object <code>==</code> +object+), * <code>false</code> otherwise. * * a = [ "a", "b", "c" ] @@ -3304,12 +3300,12 @@ * * Comparison---Returns an integer (-1, 0, * or +1) if this array is less than, equal to, or greater than - * <i>other_ary</i>. Each object in each array is compared + * +other_ary+. Each object in each array is compared * (using <=>). If any value isn't * 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 <code>Array#<=></code> if and only if they have + * ``equal'' according to Array#<=> 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. * @@ -3399,7 +3395,7 @@ * * Array Difference---Returns a new array that is a copy of * the original array, removing any items that also appear in - * <i>other_ary</i>. (If you need set-like behavior, see the + * +other_ary+. (If you need set-like behavior, see the * library class Set.) * * [ 1, 1, 2, 2, 3, 3, 4, 5 ] - [ 1, 2, 4 ] #=> [ 3, 3, 5 ] @@ -3465,7 +3461,7 @@ * ary | other_ary -> new_ary * * Set Union---Returns a new array by joining this array with - * <i>other_ary</i>, removing duplicates. + * +other_ary+, removing duplicates. * * [ "a", "b", "c" ] | [ "c", "d", "a" ] * #=> [ "a", "b", "c", "d" ] @@ -3606,8 +3602,7 @@ * ary.compact! -> ary or nil * * Removes +nil+ elements from the array. - * Returns +nil+ if no changes were made, otherwise returns - * <i>ary</i>. + * Returns +nil+ if no changes were made, otherwise returns the array. * * [ "a", nil, "b", nil, "c" ].compact! #=> [ "a", "b", "c" ] * [ "a", "b", "c" ].compact! #=> nil @@ -3664,7 +3659,7 @@ * ary.count { |item| block } -> int * * Returns the number of elements. If an argument is given, counts - * the number of elements which equals to <i>obj</i>. If a block is + * the number of elements which equals to +obj+. If a block is * given, counts the number of elements yielding a true value. * * ary = [1, 2, 4, 2] @@ -3765,7 +3760,7 @@ * * Flattens +self+ in place. * Returns <code>nil</code> if no modifications were made (i.e., - * <i>ary</i> contains no subarrays.) If the optional <i>level</i> + * the array contains no subarrays.) If the optional +level+ * argument determines the level of recursion to flatten. * * a = [ 1, 2, [3, [4, 5] ] ] @@ -3807,7 +3802,7 @@ * Returns a new array that is a one-dimensional flattening of this * array (recursively). That is, for every element that is an ar (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/