8000 [DOC] Adjust some new features wording/examples. (#9183) · ruby/ruby@570d7b2 · GitHub
[go: up one dir, main page]
Skip to content

Commit 570d7b2

Browse files
zverokzverok
authored
[DOC] Adjust some new features wording/examples. (#9183)
* Reword Range#overlap? docs last paragraph. * Docs: add explanation about Queue#freeze * Docs: Add :rescue event docs for TracePoint * Docs: Enhance Module#set_temporary_name documentation * Docs: Slightly expand Process::Status deprecations * Fix MatchData#named_captures rendering glitch * Improve Dir.fchdir examples * Adjust Refinement#target docs
1 parent d3deb1b commit 570d7b2

File tree

8 files changed

+65
-47
lines changed

8 files changed

+65
-47
lines changed

‎dir.c

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1254,10 +1254,8 @@ fchdir_restore(VALUE v)
12541254
* Dir.pwd # => "/var/spool/mail"
12551255
* dir = Dir.new('/usr')
12561256
* fd = dir.fileno
1257-
* Dir.fchdir(fd) do
1258-
* Dir.pwd # => "/usr"
1259-
* end
1260-
* Dir.pwd # => "/var/spool/mail"
1257+
* Dir.fchdir(fd)
1258+
* Dir.pwd # => "/usr"
12611259
*
12621260
* With a block, temporarily changes the working directory:
12631261
*
@@ -1271,7 +1269,9 @@ fchdir_restore(VALUE v)
12711269
*
12721270
* Dir.chdir('/var/spool/mail')
12731271
* Dir.pwd # => "/var/spool/mail"
1274-
* Dir.chdir('/tmp') do
1272+
* dir = Dir.new('/tmp')
1273+
* fd = dir.fileno
1274+
* Dir.fchdir(fd) do
12751275
* Dir.pwd # => "/tmp"
12761276
* end
12771277
* Dir.pwd # => "/var/spool/mail"

‎eval.c

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1346,9 +1346,16 @@ rb_using_module(const rb_cref_t *cref, VALUE module)
13461346

13471347
/*
13481348
* call-seq:
1349-
* target -> class
1349+
* target -> class_or_module
13501350
*
13511351
* Return the class or module refined by the receiver.
1352+
*
1353+
* module M
1354+
* refine String do
1355+
* end
1356+
* end
1357+
*
1358+
* M.refinements[0].target # => String
13521359
*/
13531360
VALUE
13541361
rb_refinement_module_get_refined_class(VALUE module)
@@ -1363,6 +1370,8 @@ rb_refinement_module_get_refined_class(VALUE module)
13631370
* call-seq:
13641371
* refined_class -> class
13651372
*
1373+
* Deprecated; prefer #target.
1374+
*
13661375
* Return the class refined by the receiver.
13671376
*/
13681377
static VALUE

‎process.c

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -576,7 +576,6 @@ proc_get_ppid(VALUE _)
576576
* stat = $? # => #<Process::Status: pid 1262862 exit 99>
577577
* stat.class # => Process::Status
578578
* stat.to_i # => 25344
579-
* stat >> 8 # => 99
580579
* stat.stopped? # => false
581580
* stat.exited? # => true
582581
* stat.exitstatus # => 99
@@ -878,7 +877,9 @@ pst_equal(VALUE st1, VALUE st2)
878877
* call-seq:
879878
* stat & mask -> integer
880879
*
881-
* This method is deprecated; use other attribute methods.
880+
* This method is deprecated as #to_i value is system-specific; use
881+
* predicate methods like #exited? or #stopped?, or getters like #exitstatus
882+
* or #stopsig.
882883
*
883884
* Returns the logical AND of the value of #to_i with +mask+:
884885
*
@@ -930,7 +931,9 @@ pst_bitand(VALUE st1, VALUE st2)
930931
* call-seq:
931932
* stat >> places -> integer
932933
*
933-
* This method is deprecated; use other predicate methods.
934+
* This method is deprecated as #to_i value is system-specific; use
935+
* predicate methods like #exited? or #stopped?, or getters like #exitstatus
936+
* or #stopsig.
934937
*
935938
* Returns the value of #to_i, shifted +places+ to the right:
936939
*

‎range.c

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2391,18 +2391,17 @@ empty_region_p(VALUE beg, VALUE end, int excl)
23912391
* (1..2).overlap?(3..4) # => false
23922392
* (1...3).overlap?(3..4) # => false
23932393
*
2394-
* This method assumes that there is no minimum value because
2395-
* Ruby lacks a standard method for determining minimum values.
2396-
* This assumption is invalid.
2397-
* For example, there is no value smaller than <tt>-Float::INFINITY</tt>,
2398-
* making <tt>(...-Float::INFINITY)</tt> an empty set.
2399-
* Consequently, <tt>(...-Float::INFINITY)</tt> has no elements in common with itself,
2400-
* yet <tt>(...-Float::INFINITY).overlap?((...-Float::INFINITY))<tt> returns
2401-
* +true+ due to this assumption.
2402-
* In general, if <tt>r = (...minimum); r.overlap?(r)</tt> returns +true+,
2403-
* where +minimum+ is a value that no value is smaller than.
2404-
* Such values include <tt>-Float::INFINITY</tt>, <tt>[]</tt>, <tt>""</tt>, and
2405-
* classes without subclasses.
2394+
* Note that the method wouldn't make any assumptions about the beginless
2395+
* range being actually empty, even if its upper bound is the minimum
2396+
* possible value of its type, so all this would return +true+:
2397+
*
2398+
* (...-Float::INFINITY).overlap?(...-Float::INFINITY) # => true
2399+
* (..."").overlap?(..."") # => true
2400+
* (...[]).overlap?(...[]) # => true
2401+
*
2402+
* Even if those ranges are effectively empty (no number can be smaller than
2403+
* <tt>-Float::INFINITY</tt>), they are still considered overlapping
2404+
* with themselves.
24062405
*
24072406
* Related: Range#cover?.
24082407
*/

‎re.c

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2334,8 +2334,8 @@ match_named_captures_iter(const OnigUChar *name, const OnigUChar *name_end,
23342334
* # => #<MatchData "01" a:"0" a:"1">
23352335
* m.named_captures #=> {"a" => "1"}
23362336
*
2337-
* If keyword argument +symbolize_names+ is given
2338-
* a true value, the keys in the resulting hash are Symbols:
2337+
* If keyword argument +symbolize_names+ is given
2338+
* a true value, the keys in the resulting hash are Symbols:
23392339
*
23402340
* m = /(?<a>.)(?<a>.)/.match("01")
23412341
* # => #<MatchData "01" a:"0" a:"1">

‎thread_sync.c

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1163,8 +1163,9 @@ NORETURN(static VALUE rb_queue_freeze(VALUE self));
11631163
* call-seq:
11641164
* freeze
11651165
*
1166-
* Raises an exception:
1167-
* Queue.new.freeze # Raises TypeError (cannot freeze #<Thread::Queue:0x...>)
1166+
* The queue can't be frozen, so this method raises an exception:
1167+
* Thread::Queue.new.freeze # Raises TypeError (cannot freeze #<Thread::Queue:0x...>)
1168+
*
11681169
*/
11691170
static VALUE
11701171
rb_queue_freeze(VALUE self)

‎trace_point.rb

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@
3737
# +:c_call+:: call a C-language routine
3838
# +:c_return+:: return from a C-language routine
3939
# +:raise+:: raise an exception
40+
# +:rescue+:: rescue an exception
4041
# +:b_call+:: event hook at block entry
4142
# +:b_return+:: event hook at block ending
4243
# +:a_call+:: event hook at all calls (+call+, +b_call+, and +c_call+)
@@ -375,7 +376,7 @@ def defined_class
375376

376377
# Return the generated binding object from event.
377378
#
378-
# Note that for +c_call+ and +c_return+ events, the method will return
379+
# Note that for +:c_call+ and +:c_return+ events, the method will return
379380
# +nil+, since C methods themselves do not have bindings.
380381
def binding
381382
Primitive.tracepoint_attr_binding
@@ -384,19 +385,19 @@ def binding
384385
# Return the trace object during event
385386
#
386387
# Same as the following, except it returns the correct object (the method
387-
# receiver) for +c_call+ and +c_return+ events:
388+
# receiver) for +:c_call+ and +:c_return+ events:
388389
#
389390
# trace.binding.eval('self')
390391
def self
391392
Primitive.tracepoint_attr_self
392393
end
393394

394-
# Return value from +:return+, +c_return+, and +b_return+ event
395+
# Return value from +:return+, +:c_return+, and +:b_return+ event
395396
def return_value
396397
Primitive.tracepoint_attr_return_value
397398
end
398399

399-
# Value from exception raised on the +:raise+ event
400+
# Value from exception raised on the +:raise+ event, or rescued on the +:rescue+ event.
400401
def raised_exception
401402
Primitive.tracepoint_attr_raised_exception
402403
end

‎variable.c

Lines changed: 23 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -162,21 +162,21 @@ is_constant_path(VALUE name)
162162
* mod.set_temporary_name(string) -> self
163163
* mod.set_temporary_name(nil) -> self
164164
*
165-
* Sets the temporary name of the module +mod+. This name is used as a prefix
166-
* for the names of constants declared in +mod+. If the module is assigned a
167-
* permanent name, the temporary name is discarded.
165+
* Sets the temporary name of the module. This name is reflected in
166+
* introspection of the module and the values that are related to it, such
167+
* as instances, constants, and methods.
168168
*
169-
* After a permanent name is assigned, a temporary name can no longer be set,
170-
* and this method raises a RuntimeError.
169+
* The name should be +nil+ or non-empty string that is not a valid constant
170+
* name (to avoid confusing between permanent and temporary names).
171171
*
172-
* If the name given is not a string or is a zero length string, this method
173-
* raises an ArgumentError.
172+
* The method can be useful to distinguish dynamically generated classes and
173+
* modules without assigning them to constants.
174174
*
175-
* The temporary name must not be a valid constant name, to avoid confusion
176-
* with actual constants. If you attempt to set a temporary name that is a
177-
* a valid constant name, this method raises an ArgumentError.
175+
* If the module is given a permanent name by assigning it to a constant,
176+
* the temporary name is discarded. A temporary name can't be assigned to
177+
* modules that have a permanent name.
178178
*
179-
* If the given name is +nil+, the module becomes anonymous.
179+
* If the given name is +nil+, the module becomes anonymous again.
180180
*
181181
* Example:
182182
*
@@ -189,15 +189,20 @@ is_constant_path(VALUE name)
189189
* m.set_temporary_name(nil) # => #<Module:0x0000000102c68f38>
190190
* m.name #=> nil
191191
*
192-
* n = Module.new
193-
* n.set_temporary_name("fake_name")
192+
* c = Class.new
193+
* c.set_temporary_name("MyClass(with description)")
194194
*
195-
* n::M = m
196-
* n::M.name #=> "fake_name::M"
197-
* N = n
195+
* c.new # => #<MyClass(with description):0x0....>
198196
*
199-
* N.name #=> "N"
200-
* N::M.name #=> "N::M"
197+
* c::M = m
198+
* c::M.name #=> "MyClass(with description)::M"
199+
*
200+
* # Assigning to a constant replaces the name with a permanent one
201+
* C = c
202+
*
203+
* C.name #=> "C"
204+
* C::M.name #=> "C::M"
205+
* c.new # => #<C:0x0....>
201206
*/
202207

203208
VALUE

0 commit comments

Comments
 (0)
0