Skip to content
Browse files

* array.c: Document #<=> return values and formatting

* bignum.c: ditto
* file.c: ditto
* object.c: ditto
* numeric.c: ditto
* rational.c: ditto
* string.c: ditto
* time.c: ditto


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@39418 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
  • Loading branch information...
1 parent 827e71b commit c2204ca328817f3d87232471a4e1de0334425752 @zzak zzak committed Feb 23, 2013
Showing with 73 additions and 40 deletions.
  1. +11 −0 ChangeLog
  2. +2 −0 array.c
  3. +5 −3 bignum.c
  4. +4 −2 file.c
  5. +14 −11 numeric.c
  6. +7 −6 object.c
  7. +3 −1 rational.c
  8. +21 −13 string.c
  9. +6 −4 time.c
View
11 ChangeLog
@@ -1,3 +1,14 @@
+Sat Feb 23 12:35:00 2013 Zachary Scott <zachary@zacharyscott.net>
+
+ * array.c: Document #<=> return values and formatting
+ * bignum.c: ditto
+ * file.c: ditto
+ * object.c: ditto
+ * numeric.c: ditto
+ * rational.c: ditto
+ * string.c: ditto
+ * time.c: ditto
+
Sat Feb 23 10:50:00 2013 Zachary Scott <zachary@zacharyscott.net>
* array.c (rb_ary_diff, rb_ary_and, rb_ary_or): Document return order
View
2 array.c
@@ -3703,6 +3703,8 @@ recursive_cmp(VALUE ary1, VALUE ary2, int recur)
* Comparison --- Returns an integer (+-1+, +0+, or <code>+1</code>) if this
* array is less than, equal to, or greater than +other_ary+.
*
+ * +nil+ is returned if the two values are incomparable.
+ *
* Each object in each array is compared (using the <=> operator).
*
* Arrays are compared in an "element-wise" manner; the first two elements
View
8 bignum.c
@@ -1520,9 +1520,11 @@ rb_integer_float_eq(VALUE x, VALUE y)
* call-seq:
* big <=> numeric -> -1, 0, +1 or nil
*
- * Comparison---Returns -1, 0, or +1 depending on whether <i>big</i> is
- * less than, equal to, or greater than <i>numeric</i>. This is the
- * basis for the tests in <code>Comparable</code>.
+ * Comparison---Returns -1, 0, or +1 depending on whether +big+ is
+ * less than, equal to, or greater than +numeric+. This is the
+ * basis for the tests in Comparable.
+ *
+ * +nil+ is returned if the two values are incomparable.
*
*/
View
6 file.c
@@ -326,8 +326,10 @@ static struct timespec stat_mtimespec(struct stat *st);
* call-seq:
* stat <=> other_stat -> -1, 0, 1, nil
*
- * Compares <code>File::Stat</code> objects by comparing their
- * respective modification times.
+ * Compares File::Stat objects by comparing their respective modification
+ * times.
+ *
+ * +nil+ is returned if the two values are incomparable.
*
* f1 = File.new("f1", "w")
* sleep 1
View
25 numeric.c
@@ -1038,10 +1038,10 @@ num_eql(VALUE x, VALUE y)
/*
* call-seq:
- * num <=> other -> 0 or nil
+ * number <=> other -> 0 or nil
*
- * Returns zero if <i>num</i> equals <i>other</i>, <code>nil</code>
- * otherwise.
+ * Returns zero if +number+ equals +other+, otherwise +nil+ is returned if the
+ * two values are incomparable.
*/
static VALUE
@@ -1129,13 +1129,15 @@ rb_dbl_cmp(double a, double b)
/*
* call-seq:
- * flt <=> real -> -1, 0, +1 or nil
+ * float <=> real -> -1, 0, +1 or nil
+ *
+ * Returns -1, 0, +1 or nil depending on whether +float+ is less than, equal
+ * to, or greater than +real+. This is the basis for the tests in Comparable.
*
- * Returns -1, 0, +1 or nil depending on whether <i>flt</i> is less
- * than, equal to, or greater than <i>real</i>. This is the basis for
- * the tests in <code>Comparable</code>.
* The result of <code>NaN <=> NaN</code> is undefined, so the
* implementation-dependent value is returned.
+ *
+ * +nil+ is returned if the two values are incomparable.
*/
static VALUE
@@ -3042,10 +3044,11 @@ fix_equal(VALUE x, VALUE y)
* call-seq:
* fix <=> numeric -> -1, 0, +1 or nil
*
- * Comparison---Returns -1, 0, +1 or nil depending on whether
- * <i>fix</i> is less than, equal to, or greater than
- * <i>numeric</i>. This is the basis for the tests in
- * <code>Comparable</code>.
+ * Comparison---Returns -1, 0, +1 or nil depending on whether +fix+ is less
+ * than, equal to, or greater than +numeric+. This is the basis for the tests
+ * in Comparable.
+ *
+ * +nil+ is returned if the two values are incomparable.
*/
static VALUE
View
13 object.c
@@ -1540,13 +1540,14 @@ rb_mod_gt(VALUE mod, VALUE arg)
/*
* call-seq:
- * mod <=> other_mod -> -1, 0, +1, or nil
+ * module <=> other_module -> -1, 0, +1, or nil
*
- * Comparison---Returns -1 if <i>mod</i> includes <i>other_mod</i>, 0 if
- * <i>mod</i> is the same as <i>other_mod</i>, and +1 if <i>mod</i> is
- * included by <i>other_mod</i>. Returns <code>nil</code> if <i>mod</i>
- * has no relationship with <i>other_mod</i> or if <i>other_mod</i> is
- * not a module.
+ * Comparison---Returns -1, 0, +1 or nil depending on whether +module+
+ * includes +other_module+, they are the same, or if +module+ is included by
+ * +other_module+. This is the basis for the tests in Comparable.
+ *
+ * Returns +nil+ if +module+ has no relationship with +other_module+, if
+ * +other_module+ is not a module, or if the two values are incomparable.
*/
static VALUE
View
4 rational.c
@@ -1024,10 +1024,12 @@ nurat_expt(VALUE self, VALUE other)
/*
* call-seq:
- * rat <=> numeric -> -1, 0, +1 or nil
+ * rational <=> numeric -> -1, 0, +1 or nil
*
* Performs comparison and returns -1, 0, or +1.
*
+ * +nil+ is returned if the two values are incomparable.
+ *
* Rational(2, 3) <=> Rational(2, 3) #=> 0
* Rational(5) <=> 5 #=> 0
* Rational(2,3) <=> Rational(1,3) #=> 1
View
34 string.c
@@ -2358,20 +2358,22 @@ rb_str_eql(VALUE str1, VALUE str2)
/*
* call-seq:
- * str <=> other_str -> -1, 0, +1 or nil
+ * string <=> other_string -> -1, 0, +1 or nil
*
- * Comparison---Returns -1 if <i>other_str</i> is greater than, 0 if
- * <i>other_str</i> is equal to, and +1 if <i>other_str</i> is less than
- * <i>str</i>. If the strings are of different lengths, and the strings are
- * equal when compared up to the shortest length, then the longer string is
- * considered greater than the shorter one. In older versions of Ruby, setting
- * <code>$=</code> allowed case-insensitive comparisons; this is now deprecated
- * in favor of using <code>String#casecmp</code>.
+ *
+ * Comparison---Returns -1, 0, +1 or nil depending on whether +string+ is less
+ * than, equal to, or greater than +other_string+.
+ *
+ * +nil+ is returned if the two values are incomparable.
+ *
+ * If the strings are of different lengths, and the strings are equal when
+ * compared up to the shortest length, then the longer string is considered
+ * greater than the shorter one.
*
* <code><=></code> is the basis for the methods <code><</code>,
- * <code><=</code>, <code>></code>, <code>>=</code>, and <code>between?</code>,
- * included from module <code>Comparable</code>. The method
- * <code>String#==</code> does not use <code>Comparable#==</code>.
+ * <code><=</code>, <code>></code>, <code>>=</code>, and
+ * <code>between?</code>, included from module Comparable. The method
+ * String#== does not use Comparable#==.
*
* "abcdef" <=> "abcde" #=> 1
* "abcdef" <=> "abcdef" #=> 0
@@ -7946,9 +7948,15 @@ sym_succ(VALUE sym)
/*
* call-seq:
*
- * str <=> other -> -1, 0, +1 or nil
+ * symbol <=> other_symbol -> -1, 0, +1 or nil
+ *
+ * Compares +symbol+ with +other_symbol+ after calling #to_s on each of the
+ * symbols. Returns -1, 0, +1 or nil depending on whether +symbol+ is less
+ * than, equal to, or greater than +other_symbol+.
+ *
+ * +nil+ is returned if the two values are incomparable.
*
- * Compares _sym_ with _other_ in string form.
+ * See String#<=> for more information.
*/
static VALUE
View
10 time.c
@@ -3334,10 +3334,12 @@ time_subsec(VALUE time)
* call-seq:
* time <=> other_time -> -1, 0, +1 or nil
*
- * Comparison---Compares _time_ with +other_time+.
- * The return value is ++1+ if _time_ is greater than
- * +other_time+, +0+ if _time_ is equal to +other_time+ and
- * +-1+ if _time_ is smaller than +other_time+.
+ * Comparison---Compares +time+ with +other_time+.
+ *
+ * -1, 0, +1 or nil depending on whether +time+ is less than, equal to, or
+ * greater than +other_time+.
+ *
+ * +nil+ is returned if the two values are incomparable.
*
* t = Time.now #=> 2007-11-19 08:12:12 -0600
* t2 = t + 2592000 #=> 2007-12-19 08:12:12 -0600

0 comments on commit c2204ca

Please sign in to comment.
Something went wrong with that request. Please try again.