[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
This commit is contained in:
Victor Shepelev 2023-12-14 23:01:48 +02:00 коммит произвёл GitHub
Родитель d3deb1b823
Коммит 570d7b2c3e
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
8 изменённых файлов: 65 добавлений и 47 удалений

10
dir.c
Просмотреть файл

@ -1254,10 +1254,8 @@ fchdir_restore(VALUE v)
* Dir.pwd # => "/var/spool/mail"
* dir = Dir.new('/usr')
* fd = dir.fileno
* Dir.fchdir(fd) do
* Dir.pwd # => "/usr"
* end
* Dir.pwd # => "/var/spool/mail"
* Dir.fchdir(fd)
* Dir.pwd # => "/usr"
*
* With a block, temporarily changes the working directory:
*
@ -1271,7 +1269,9 @@ fchdir_restore(VALUE v)
*
* Dir.chdir('/var/spool/mail')
* Dir.pwd # => "/var/spool/mail"
* Dir.chdir('/tmp') do
* dir = Dir.new('/tmp')
* fd = dir.fileno
* Dir.fchdir(fd) do
* Dir.pwd # => "/tmp"
* end
* Dir.pwd # => "/var/spool/mail"

11
eval.c
Просмотреть файл

@ -1346,9 +1346,16 @@ rb_using_module(const rb_cref_t *cref, VALUE module)
/*
* call-seq:
* target -> class
* target -> class_or_module
*
* Return the class or module refined by the receiver.
*
* module M
* refine String do
* end
* end
*
* M.refinements[0].target # => String
*/
VALUE
rb_refinement_module_get_refined_class(VALUE module)
@ -1363,6 +1370,8 @@ rb_refinement_module_get_refined_class(VALUE module)
* call-seq:
* refined_class -> class
*
* Deprecated; prefer #target.
*
* Return the class refined by the receiver.
*/
static VALUE

Просмотреть файл

@ -576,7 +576,6 @@ proc_get_ppid(VALUE _)
* stat = $? # => #<Process::Status: pid 1262862 exit 99>
* stat.class # => Process::Status
* stat.to_i # => 25344
* stat >> 8 # => 99
* stat.stopped? # => false
* stat.exited? # => true
* stat.exitstatus # => 99
@ -878,7 +877,9 @@ pst_equal(VALUE st1, VALUE st2)
* call-seq:
* stat & mask -> integer
*
* This method is deprecated; use other attribute methods.
* This method is deprecated as #to_i value is system-specific; use
* predicate methods like #exited? or #stopped?, or getters like #exitstatus
* or #stopsig.
*
* Returns the logical AND of the value of #to_i with +mask+:
*
@ -930,7 +931,9 @@ pst_bitand(VALUE st1, VALUE st2)
* call-seq:
* stat >> places -> integer
*
* This method is deprecated; use other predicate methods.
* This method is deprecated as #to_i value is system-specific; use
* predicate methods like #exited? or #stopped?, or getters like #exitstatus
* or #stopsig.
*
* Returns the value of #to_i, shifted +places+ to the right:
*

23
range.c
Просмотреть файл

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

4
re.c
Просмотреть файл

@ -2334,8 +2334,8 @@ match_named_captures_iter(const OnigUChar *name, const OnigUChar *name_end,
* # => #<MatchData "01" a:"0" a:"1">
* m.named_captures #=> {"a" => "1"}
*
* If keyword argument +symbolize_names+ is given
* a true value, the keys in the resulting hash are Symbols:
* If keyword argument +symbolize_names+ is given
* a true value, the keys in the resulting hash are Symbols:
*
* m = /(?<a>.)(?<a>.)/.match("01")
* # => #<MatchData "01" a:"0" a:"1">

Просмотреть файл

@ -1163,8 +1163,9 @@ NORETURN(static VALUE rb_queue_freeze(VALUE self));
* call-seq:
* freeze
*
* Raises an exception:
* Queue.new.freeze # Raises TypeError (cannot freeze #<Thread::Queue:0x...>)
* The queue can't be frozen, so this method raises an exception:
* Thread::Queue.new.freeze # Raises TypeError (cannot freeze #<Thread::Queue:0x...>)
*
*/
static VALUE
rb_queue_freeze(VALUE self)

Просмотреть файл

@ -37,6 +37,7 @@
# +:c_call+:: call a C-language routine
# +:c_return+:: return from a C-language routine
# +:raise+:: raise an exception
# +:rescue+:: rescue an exception
# +:b_call+:: event hook at block entry
# +:b_return+:: event hook at block ending
# +:a_call+:: event hook at all calls (+call+, +b_call+, and +c_call+)
@ -375,7 +376,7 @@ class TracePoint
# Return the generated binding object from event.
#
# Note that for +c_call+ and +c_return+ events, the method will return
# Note that for +:c_call+ and +:c_return+ events, the method will return
# +nil+, since C methods themselves do not have bindings.
def binding
Primitive.tracepoint_attr_binding
@ -384,19 +385,19 @@ class TracePoint
# Return the trace object during event
#
# Same as the following, except it returns the correct object (the method
# receiver) for +c_call+ and +c_return+ events:
# receiver) for +:c_call+ and +:c_return+ events:
#
# trace.binding.eval('self')
def self
Primitive.tracepoint_attr_self
end
# Return value from +:return+, +c_return+, and +b_return+ event
# Return value from +:return+, +:c_return+, and +:b_return+ event
def return_value
Primitive.tracepoint_attr_return_value
end
# Value from exception raised on the +:raise+ event
# Value from exception raised on the +:raise+ event, or rescued on the +:rescue+ event.
def raised_exception
Primitive.tracepoint_attr_raised_exception
end

Просмотреть файл

@ -162,21 +162,21 @@ is_constant_path(VALUE name)
* mod.set_temporary_name(string) -> self
* mod.set_temporary_name(nil) -> self
*
* Sets the temporary name of the module +mod+. This name is used as a prefix
* for the names of constants declared in +mod+. If the module is assigned a
* permanent name, the temporary name is discarded.
* Sets the temporary name of the module. This name is reflected in
* introspection of the module and the values that are related to it, such
* as instances, constants, and methods.
*
* After a permanent name is assigned, a temporary name can no longer be set,
* and this method raises a RuntimeError.
* The name should be +nil+ or non-empty string that is not a valid constant
* name (to avoid confusing between permanent and temporary names).
*
* If the name given is not a string or is a zero length string, this method
* raises an ArgumentError.
* The method can be useful to distinguish dynamically generated classes and
* modules without assigning them to constants.
*
* The temporary name must not be a valid constant name, to avoid confusion
* with actual constants. If you attempt to set a temporary name that is a
* a valid constant name, this method raises an ArgumentError.
* If the module is given a permanent name by assigning it to a constant,
* the temporary name is discarded. A temporary name can't be assigned to
* modules that have a permanent name.
*
* If the given name is +nil+, the module becomes anonymous.
* If the given name is +nil+, the module becomes anonymous again.
*
* Example:
*
@ -189,15 +189,20 @@ is_constant_path(VALUE name)
* m.set_temporary_name(nil) # => #<Module:0x0000000102c68f38>
* m.name #=> nil
*
* n = Module.new
* n.set_temporary_name("fake_name")
* c = Class.new
* c.set_temporary_name("MyClass(with description)")
*
* n::M = m
* n::M.name #=> "fake_name::M"
* N = n
* c.new # => #<MyClass(with description):0x0....>
*
* N.name #=> "N"
* N::M.name #=> "N::M"
* c::M = m
* c::M.name #=> "MyClass(with description)::M"
*
* # Assigning to a constant replaces the name with a permanent one
* C = c
*
* C.name #=> "C"
* C::M.name #=> "C::M"
* c.new # => #<C:0x0....>
*/
VALUE