From 8ef7ecbe9c354d82f26a3bad37c156ffe1ff2e86 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 20 Dec 2023 11:15:39 -0600 Subject: [PATCH 01/10] RDoc for Complex --- complex.c | 59 +++++++++++++++++++++++++------------------------------ 1 file changed, 27 insertions(+), 32 deletions(-) diff --git a/complex.c b/complex.c index 5b91c5f2407e4d..544a5127d6770c 100644 --- a/complex.c +++ b/complex.c @@ -1779,14 +1779,15 @@ rb_dbl_complex_new(double real, double imag) /* * call-seq: - * cmp.to_i -> integer + * to_i -> integer * - * Returns the value as an integer if possible (the imaginary part - * should be exactly zero). + * Returns the value of self.real as an Integer, if possible: * - * Complex(1, 0).to_i #=> 1 - * Complex(1, 0.0).to_i # RangeError - * Complex(1, 2).to_i # RangeError + * Complex(1, 0).to_i # => 1 + * Complex(1, Rational(0, 1)).to_i # => 1 + * + * Raises RangeError if self.imag is not exactly zero + * (either Integer(0) or Rational(0, _n_)). */ static VALUE nucomp_to_i(VALUE self) @@ -1802,14 +1803,15 @@ nucomp_to_i(VALUE self) /* * call-seq: - * cmp.to_f -> float + * to_f -> float + * + * Returns the value of self.real as a Float, if possible: * - * Returns the value as a float if possible (the imaginary part should - * be exactly zero). + * Complex(1, 0).to_f # => 1.0 + * Complex(1, Rational(0, 1)).to_f # => 1.0 * - * Complex(1, 0).to_f #=> 1.0 - * Complex(1, 0.0).to_f # RangeError - * Complex(1, 2).to_f # RangeError + * Raises RangeError if self.imag is not exactly zero + * (either Integer(0) or Rational(0, _n_)). */ static VALUE nucomp_to_f(VALUE self) @@ -1825,16 +1827,17 @@ nucomp_to_f(VALUE self) /* * call-seq: - * cmp.to_r -> rational + * cmp.to_r -> rational + * + * Returns the value of self.real as a Rational, if possible: * - * Returns the value as a rational if possible (the imaginary part - * should be exactly zero). + * Complex(1, 0).to_r # => (1/1) + * Complex(1, Rational(0, 1)).to_r # => (1/1) * - * Complex(1, 0).to_r #=> (1/1) - * Complex(1, 0.0).to_r # RangeError - * Complex(1, 2).to_r # RangeError + * Raises RangeError if self.imag is not exactly zero + * (either Integer(0) or Rational(0, _n_)). * - * See rationalize. + * Related: Complex#rationalize. */ static VALUE nucomp_to_r(VALUE self) @@ -1850,16 +1853,11 @@ nucomp_to_r(VALUE self) /* * call-seq: - * cmp.rationalize([eps]) -> rational + * rationalize(epsilon = nil) -> rational * - * Returns the value as a rational if possible (the imaginary part - * should be exactly zero). + * Equivalent to Complex#to_r. * - * Complex(1.0/3, 0).rationalize #=> (1/3) - * Complex(1, 0.0).rationalize # RangeError - * Complex(1, 2).rationalize # RangeError - * - * See to_r. + * (Argument +epsilon+ is ignored.) */ static VALUE nucomp_rationalize(int argc, VALUE *argv, VALUE self) @@ -1877,12 +1875,9 @@ nucomp_rationalize(int argc, VALUE *argv, VALUE self) /* * call-seq: - * complex.to_c -> self - * - * Returns self. + * to_c -> self * - * Complex(2).to_c #=> (2+0i) - * Complex(-8, 6).to_c #=> (-8+6i) + * Returns +self+. */ static VALUE nucomp_to_c(VALUE self) From 3e6d22cb843232c62426ad882b1991ab21b7755e Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Fri, 22 Dec 2023 08:31:45 -0600 Subject: [PATCH 02/10] RDoc for Complex --- complex.c | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/complex.c b/complex.c index 544a5127d6770c..828613586650ef 100644 --- a/complex.c +++ b/complex.c @@ -1827,7 +1827,7 @@ nucomp_to_f(VALUE self) /* * call-seq: - * cmp.to_r -> rational + * to_r -> rational * * Returns the value of self.real as a Rational, if possible: * @@ -1855,9 +1855,32 @@ nucomp_to_r(VALUE self) * call-seq: * rationalize(epsilon = nil) -> rational * - * Equivalent to Complex#to_r. + * Returns a Rational object whose value is exactly or approximately + * equivalent to that of self.real. * - * (Argument +epsilon+ is ignored.) + * With no argument +epsilon+ given, equivalent to Complex#to_r: + * + * Complex(1, 0).rationalize # => (1/1) + * Complex(1, Rational(0, 1)).rationalize # => (1/1) + * Complex(3.14159, 0).rationalize # => (314159/100000) + * + * With argument +epsilon+ given, returns a \Rational object + * whose value is exactly or approximately equal to that of self.real + * to the given precision: + * + * Complex(3.14159, 0).rationalize(0.1) # => (16/5) + * Complex(3.14159, 0).rationalize(0.01) # => (22/7) + * Complex(3.14159, 0).rationalize(0.001) # => (201/64) + * Complex(3.14159, 0).rationalize(0.0001) # => (333/106) + * Complex(3.14159, 0).rationalize(0.00001) # => (355/113) + * Complex(3.14159, 0).rationalize(0.000001) # => (7433/2366) + * Complex(3.14159, 0).rationalize(0.0000001) # => (9208/2931) + * Complex(3.14159, 0).rationalize(0.00000001) # => (47460/15107) + * Complex(3.14159, 0).rationalize(0.000000001) # => (76149/24239) + * Complex(3.14159, 0).rationalize(0.0000000001) # => (314159/100000) + * Complex(3.14159, 0).rationalize(0.0) # => (3537115888337719/1125899906842624) + * + * Related: Complex#to_r. */ static VALUE nucomp_rationalize(int argc, VALUE *argv, VALUE self) From 90c1f19172f78bc4c365bbf006240aff3616c03e Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Fri, 22 Dec 2023 08:36:54 -0600 Subject: [PATCH 03/10] RDoc for Complex --- complex.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/complex.c b/complex.c index 828613586650ef..1517a5d0686ffc 100644 --- a/complex.c +++ b/complex.c @@ -1862,7 +1862,7 @@ nucomp_to_r(VALUE self) * * Complex(1, 0).rationalize # => (1/1) * Complex(1, Rational(0, 1)).rationalize # => (1/1) - * Complex(3.14159, 0).rationalize # => (314159/100000) + * Complex(3.14159, 0).rationalize # => (314159/100000) * * With argument +epsilon+ given, returns a \Rational object * whose value is exactly or approximately equal to that of self.real From 97b277d96d0514920ddbd48b82224b625b5dfd92 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Fri, 22 Dec 2023 09:41:42 -0600 Subject: [PATCH 04/10] RDoc for Complex --- complex.c | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/complex.c b/complex.c index 1517a5d0686ffc..d0b7a3541d722a 100644 --- a/complex.c +++ b/complex.c @@ -1858,7 +1858,8 @@ nucomp_to_r(VALUE self) * Returns a Rational object whose value is exactly or approximately * equivalent to that of self.real. * - * With no argument +epsilon+ given, equivalent to Complex#to_r: + * With no argument +epsilon+ given, returns a \Rational object + * whose value is exactly equal to that of self.real: * * Complex(1, 0).rationalize # => (1/1) * Complex(1, Rational(0, 1)).rationalize # => (1/1) From 35788b6ebfd57404111ea87c20ef807b5fba27de Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Fri, 22 Dec 2023 20:20:51 -0600 Subject: [PATCH 05/10] Update complex.c Co-authored-by: Peter Zhu --- complex.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/complex.c b/complex.c index d0b7a3541d722a..d104bb8dea8b2e 100644 --- a/complex.c +++ b/complex.c @@ -1859,7 +1859,7 @@ nucomp_to_r(VALUE self) * equivalent to that of self.real. * * With no argument +epsilon+ given, returns a \Rational object - * whose value is exactly equal to that of self.real: + * whose value is exactly equal to that of self.real.rationalize: * * Complex(1, 0).rationalize # => (1/1) * Complex(1, Rational(0, 1)).rationalize # => (1/1) From 1659b2d1c5c49d480d662888a43d07fe919fa00f Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sat, 23 Dec 2023 11:19:13 -0600 Subject: [PATCH 06/10] Clean up doc for File#flock --- file.c | 102 ++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 65 insertions(+), 37 deletions(-) diff --git a/file.c b/file.c index fd1fbf2d971d42..acdee79c5259ce 100644 --- a/file.c +++ b/file.c @@ -5222,47 +5222,75 @@ rb_thread_flock(void *data) return (VALUE)ret; } -/* +/* :markup: markdown + * * call-seq: - * file.flock(locking_constant) -> 0 or false - * - * Locks or unlocks a file according to locking_constant (a - * logical or of the values in the table below). - * Returns false if File::LOCK_NB is specified and the - * operation would otherwise have blocked. Not available on all - * platforms. - * - * Locking constants (in class File): - * - * LOCK_EX | Exclusive lock. Only one process may hold an - * | exclusive lock for a given file at a time. - * ----------+------------------------------------------------ - * LOCK_NB | Don't block when locking. May be combined - * | with other lock options using logical or. - * ----------+------------------------------------------------ - * LOCK_SH | Shared lock. Multiple processes may each hold a - * | shared lock for a given file at the same time. - * ----------+------------------------------------------------ - * LOCK_UN | Unlock. + * flock(locking_constant) -> 0 or false + * + * Locks or unlocks a file according to the given `locking_constant`, + * a bitwise OR of the values in the table below. + * + * Not available on all platforms. * + * Returns `false` if `File::LOCK_NB` is specified and the operation would have blocked; + * otherwise returns `0`. + *
+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Locking Constants
ConstantLockEffect
File::LOCK_EXExclusiveOnly one process may hold an exclusive lock for self at a time.
File::LOCK_NBNon-blocking + * No blocking; may be combined with other `File::LOCK_SH` or `File::LOCK_EX` + * using the bitwise OR operator |. + *
File::LOCK_SHSharedMultiple processes may each hold a shared lock for self at the same time.
File::LOCK_UNNoneNo locking.
+ * + *
* Example: * - * # update a counter using write lock - * # don't use "w" because it truncates the file before lock. - * File.open("counter", File::RDWR|File::CREAT, 0644) {|f| - * f.flock(File::LOCK_EX) - * value = f.read.to_i + 1 - * f.rewind - * f.write("#{value}\n") - * f.flush - * f.truncate(f.pos) - * } - * - * # read the counter using read lock - * File.open("counter", "r") {|f| - * f.flock(File::LOCK_SH) - * p f.read - * } + * ```ruby + * # Update a counter using an exclusive lock. + * # Don't use File::WRONLY because it truncates the file. + * File.open('counter', File::RDWR | File::CREAT, 0644) do |f| + * f.flock(File::LOCK_EX) + * value = f.read.to_i + 1 + * f.rewind + * f.write("#{value}\n") + * f.flush + * f.truncate(f.pos) + * end + * + * # Read the counter using a shared lock. + * File.open('counter', 'r') do |f| + * f.flock(File::LOCK_SH) + * f.read + * end + * ``` * */ From 17b9070487ebb20199d76da8e3f7ffe18aff6f3d Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sat, 23 Dec 2023 12:21:42 -0600 Subject: [PATCH 07/10] RDoc for Complex --- complex.c | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/complex.c b/complex.c index 5b91c5f2407e4d..f18b10145d1382 100644 --- a/complex.c +++ b/complex.c @@ -789,8 +789,6 @@ rb_complex_real(VALUE self) * * Complex.polar(1, Math::PI/4).imag # => 0.7071067811865476 # Square root of 2. * - * \Complex#imaginary is an alias for \Complex#imag. - * */ VALUE rb_complex_imag(VALUE self) @@ -1001,7 +999,6 @@ f_divide(VALUE self, VALUE other, * Complex(9, 8) / 4 # => ((9/4)+(2/1)*i) * Complex(20, 9) / 9.8 # => (2.0408163265306123+0.9183673469387754i) * - * Complex#quo is an alias for Complex#/. */ VALUE rb_complex_div(VALUE self, VALUE other) @@ -1327,7 +1324,6 @@ nucomp_coerce(VALUE self, VALUE other) * * Complex.rectangular(1, 1).abs # => 1.4142135623730951 # The square root of 2. * - * Complex#magnitude is an alias for Complex#abs. */ VALUE rb_complex_abs(VALUE self) @@ -1388,7 +1384,6 @@ nucomp_abs2(VALUE self) * * Complex.polar(1, 1.0/3).arg # => 0.33333333333333326 * - * Complex#angle and Complex#phase are aliases for Complex#arg. */ VALUE rb_complex_arg(VALUE self) @@ -1454,7 +1449,6 @@ nucomp_polar(VALUE self) * * Complex.rect(1, 2).conj # => (1-2i) * - * Complex#conjugate is an alias for Complex#conj. */ VALUE rb_complex_conjugate(VALUE self) @@ -1547,6 +1541,18 @@ rb_complex_hash(VALUE self) return v; } +/* + * :call-seq: + * hash -> integer + * + * Returns the integer hash value for +self+. + * + * Two \Complex objects created from the same values will have the same hash value + * (and will compare using #eql?): + * + * Complex(1, 2).hash == Complex(1, 2).hash # => true + * + */ static VALUE nucomp_hash(VALUE self) { From 3b3b397fd898bcf708d3e947d802e41955aa435d Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Sat, 23 Dec 2023 12:42:00 -0600 Subject: [PATCH 08/10] Update file.c Co-authored-by: Peter Zhu --- file.c | 62 +++++++++++++++++++++++++++++----------------------------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/file.c b/file.c index acdee79c5259ce..9bf6c787384da6 100644 --- a/file.c +++ b/file.c @@ -5237,37 +5237,37 @@ rb_thread_flock(void *data) *
* * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * *
Locking Constants
ConstantLockEffect
File::LOCK_EXExclusiveOnly one process may hold an exclusive lock for self at a time.
File::LOCK_NBNon-blocking - * No blocking; may be combined with other `File::LOCK_SH` or `File::LOCK_EX` - * using the bitwise OR operator |. - *
File::LOCK_SHSharedMultiple processes may each hold a shared lock for self at the same time.
File::LOCK_UNNoneNo locking.
Locking Constants
ConstantLockEffect
File::LOCK_EXExclusiveOnly one process may hold an exclusive lock for self at a time.
File::LOCK_NBNon-blocking + * No blocking; may be combined with other `File::LOCK_SH` or `File::LOCK_EX` + * using the bitwise OR operator |. + *
File::LOCK_SHSharedMultiple processes may each hold a shared lock for self at the same time.
File::LOCK_UNNoneNo locking.
* *
From 17c93ad47aa34fff01778c7b1d2b0e61c1c71efd Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sat, 23 Dec 2023 12:53:26 -0600 Subject: [PATCH 09/10] Update file.c --- file.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/file.c b/file.c index 9bf6c787384da6..fee3840452081a 100644 --- a/file.c +++ b/file.c @@ -5265,8 +5265,8 @@ rb_thread_flock(void *data) * * * File::LOCK_UN - * None - * No locking. + * Unlock + * Remove an existing lock held by this process. * * * From 6f2442a78ef7cb905d84413b13309fe5c1072615 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sat, 23 Dec 2023 14:45:55 -0600 Subject: [PATCH 10/10] Update file.c --- complex.c | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/complex.c b/complex.c index 9057771b5cf989..d104bb8dea8b2e 100644 --- a/complex.c +++ b/complex.c @@ -789,6 +789,8 @@ rb_complex_real(VALUE self) * * Complex.polar(1, Math::PI/4).imag # => 0.7071067811865476 # Square root of 2. * + * \Complex#imaginary is an alias for \Complex#imag. + * */ VALUE rb_complex_imag(VALUE self) @@ -999,6 +1001,7 @@ f_divide(VALUE self, VALUE other, * Complex(9, 8) / 4 # => ((9/4)+(2/1)*i) * Complex(20, 9) / 9.8 # => (2.0408163265306123+0.9183673469387754i) * + * Complex#quo is an alias for Complex#/. */ VALUE rb_complex_div(VALUE self, VALUE other) @@ -1324,6 +1327,7 @@ nucomp_coerce(VALUE self, VALUE other) * * Complex.rectangular(1, 1).abs # => 1.4142135623730951 # The square root of 2. * + * Complex#magnitude is an alias for Complex#abs. */ VALUE rb_complex_abs(VALUE self) @@ -1384,6 +1388,7 @@ nucomp_abs2(VALUE self) * * Complex.polar(1, 1.0/3).arg # => 0.33333333333333326 * + * Complex#angle and Complex#phase are aliases for Complex#arg. */ VALUE rb_complex_arg(VALUE self) @@ -1449,6 +1454,7 @@ nucomp_polar(VALUE self) * * Complex.rect(1, 2).conj # => (1-2i) * + * Complex#conjugate is an alias for Complex#conj. */ VALUE rb_complex_conjugate(VALUE self) @@ -1541,18 +1547,6 @@ rb_complex_hash(VALUE self) return v; } -/* - * :call-seq: - * hash -> integer - * - * Returns the integer hash value for +self+. - * - * Two \Complex objects created from the same values will have the same hash value - * (and will compare using #eql?): - * - * Complex(1, 2).hash == Complex(1, 2).hash # => true - * - */ static VALUE nucomp_hash(VALUE self) {