mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
merge revision(s) 57751,57753,57755:
fileutils.rb: improve rdoc for FileUtils * lib/fileutils.rb: [DOC] fix invalid example code to make it syntax highlighted, fix rdoc for lists, nodoc internal methods, avoid a dangerous example. hash.c: [DOC] fix book title in example struct.c: improve rdoc for Struct * struct.c: [DOC] improve examples for ::new, improve #dig example, simplify #select example, use consistent style for return values, fix typos and example code style, remove duplicate cross reference. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_2_4@57918 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
naruse
parent
7ac478693c
commit
a5d26fb862
4 changed files with 52 additions and 43 deletions
2
hash.c
2
hash.c
|
|
@ -4375,7 +4375,7 @@ env_update(VALUE env, VALUE hash)
|
|||
* Hashes are an easy way to represent data structures, such as
|
||||
*
|
||||
* books = {}
|
||||
* books[:matz] = "The Ruby Language"
|
||||
* books[:matz] = "The Ruby Programming Language"
|
||||
* books[:black] = "The Well-Grounded Rubyist"
|
||||
*
|
||||
* Hashes are also commonly used as a way to have named parameters in
|
||||
|
|
|
|||
|
|
@ -16,7 +16,7 @@
|
|||
# require 'fileutils'
|
||||
#
|
||||
# FileUtils.cd(dir, options)
|
||||
# FileUtils.cd(dir, options) {|dir| .... }
|
||||
# FileUtils.cd(dir, options) {|dir| block }
|
||||
# FileUtils.pwd()
|
||||
# FileUtils.mkdir(dir, options)
|
||||
# FileUtils.mkdir(list, options)
|
||||
|
|
@ -38,7 +38,7 @@
|
|||
# FileUtils.rm(list, options)
|
||||
# FileUtils.rm_r(list, options)
|
||||
# FileUtils.rm_rf(list, options)
|
||||
# FileUtils.install(src, dest, mode = <src's>, options)
|
||||
# FileUtils.install(src, dest, options)
|
||||
# FileUtils.chmod(mode, list, options)
|
||||
# FileUtils.chmod_R(mode, list, options)
|
||||
# FileUtils.chown(user, group, list, options)
|
||||
|
|
@ -112,7 +112,7 @@ module FileUtils
|
|||
# FileUtils.cd('/', :verbose => true) # chdir and report it
|
||||
#
|
||||
# FileUtils.cd('/') do # chdir
|
||||
# [...] # do something
|
||||
# # ... # do something
|
||||
# end # return to original directory
|
||||
#
|
||||
def cd(dir, verbose: nil, &block) # :yield: dir
|
||||
|
|
@ -144,7 +144,7 @@ module FileUtils
|
|||
end
|
||||
module_function :uptodate?
|
||||
|
||||
def remove_trailing_slash(dir)
|
||||
def remove_trailing_slash(dir) #:nodoc:
|
||||
dir == '/' ? dir : dir.chomp(?/)
|
||||
end
|
||||
private_module_function :remove_trailing_slash
|
||||
|
|
@ -175,10 +175,11 @@ module FileUtils
|
|||
# FileUtils.mkdir_p '/usr/local/lib/ruby'
|
||||
#
|
||||
# causes to make following directories, if it does not exist.
|
||||
# * /usr
|
||||
# * /usr/local
|
||||
# * /usr/local/lib
|
||||
# * /usr/local/lib/ruby
|
||||
#
|
||||
# * /usr
|
||||
# * /usr/local
|
||||
# * /usr/local/lib
|
||||
# * /usr/local/lib/ruby
|
||||
#
|
||||
# You can pass several directories at a time in a list.
|
||||
#
|
||||
|
|
@ -325,7 +326,8 @@ module FileUtils
|
|||
|
||||
#
|
||||
# Same as
|
||||
# #ln_s(src, dest, :force => true)
|
||||
#
|
||||
# FileUtils.ln_s(src, dest, :force => true)
|
||||
#
|
||||
def ln_sf(src, dest, noop: nil, verbose: nil)
|
||||
ln_s src, dest, force: true, noop: noop, verbose: verbose
|
||||
|
|
@ -508,7 +510,7 @@ module FileUtils
|
|||
#
|
||||
# Equivalent to
|
||||
#
|
||||
# #rm(list, :force => true)
|
||||
# FileUtils.rm(list, :force => true)
|
||||
#
|
||||
def rm_f(list, noop: nil, verbose: nil)
|
||||
rm list, force: true, noop: noop, verbose: verbose
|
||||
|
|
@ -524,7 +526,7 @@ module FileUtils
|
|||
# StandardError when :force option is set.
|
||||
#
|
||||
# FileUtils.rm_r Dir.glob('/tmp/*')
|
||||
# FileUtils.rm_r '/', :force => true # :-)
|
||||
# FileUtils.rm_r 'some_dir', :force => true
|
||||
#
|
||||
# WARNING: This method causes local vulnerability
|
||||
# if one of parent directories or removing directory tree are world
|
||||
|
|
@ -554,7 +556,7 @@ module FileUtils
|
|||
#
|
||||
# Equivalent to
|
||||
#
|
||||
# #rm_r(list, :force => true)
|
||||
# FileUtils.rm_r(list, :force => true)
|
||||
#
|
||||
# WARNING: This method causes local vulnerability.
|
||||
# Read the documentation of #rm_r first.
|
||||
|
|
@ -574,9 +576,9 @@ module FileUtils
|
|||
# (time-of-check-to-time-of-use) local security vulnerability of #rm_r.
|
||||
# #rm_r causes security hole when:
|
||||
#
|
||||
# * Parent directory is world writable (including /tmp).
|
||||
# * Removing directory tree includes world writable directory.
|
||||
# * The system has symbolic link.
|
||||
# * Parent directory is world writable (including /tmp).
|
||||
# * Removing directory tree includes world writable directory.
|
||||
# * The system has symbolic link.
|
||||
#
|
||||
# To avoid this security hole, this method applies special preprocess.
|
||||
# If +path+ is a directory, this method chown(2) and chmod(2) all
|
||||
|
|
@ -594,8 +596,8 @@ module FileUtils
|
|||
#
|
||||
# For details of this security vulnerability, see Perl's case:
|
||||
#
|
||||
# http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2005-0448
|
||||
# http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2004-0452
|
||||
# * http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2005-0448
|
||||
# * http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2004-0452
|
||||
#
|
||||
# For fileutils.rb, this vulnerability is reported in [ruby-dev:26100].
|
||||
#
|
||||
|
|
@ -799,7 +801,7 @@ module FileUtils
|
|||
end
|
||||
private_module_function :user_mask
|
||||
|
||||
def apply_mask(mode, user_mask, op, mode_mask)
|
||||
def apply_mask(mode, user_mask, op, mode_mask) #:nodoc:
|
||||
case op
|
||||
when '='
|
||||
(mode & ~user_mask) | (user_mask & mode_mask)
|
||||
|
|
|
|||
53
struct.c
53
struct.c
|
|
@ -436,10 +436,10 @@ rb_struct_define_under(VALUE outer, const char *name, ...)
|
|||
|
||||
/*
|
||||
* call-seq:
|
||||
* Struct.new([class_name] [, member_name]+>) -> StructClass
|
||||
* Struct.new([class_name] [, member_name]+>) {|StructClass| block } -> StructClass
|
||||
* StructClass.new(value, ...) -> obj
|
||||
* StructClass[value, ...] -> obj
|
||||
* Struct.new([class_name] [, member_name]+) -> StructClass
|
||||
* Struct.new([class_name] [, member_name]+) {|StructClass| block } -> StructClass
|
||||
* StructClass.new(value, ...) -> object
|
||||
* StructClass[value, ...] -> object
|
||||
*
|
||||
* The first two forms are used to create a new Struct subclass +class_name+
|
||||
* that can contain a value for each +member_name+. This subclass can be
|
||||
|
|
@ -457,6 +457,12 @@ rb_struct_define_under(VALUE outer, const char *name, ...)
|
|||
* Struct::Customer.new("Dave", "123 Main")
|
||||
* #=> #<struct Struct::Customer name="Dave", address="123 Main">
|
||||
*
|
||||
* # Create a structure named by its constant
|
||||
* Customer = Struct.new(:name, :address)
|
||||
* #=> Customer
|
||||
* Customer.new("Dave", "123 Main")
|
||||
* #=> #<struct Customer name="Dave", address="123 Main">
|
||||
*
|
||||
* If a block is given it will be evaluated in the context of
|
||||
* +StructClass+, passing the created class as a parameter:
|
||||
*
|
||||
|
|
@ -465,7 +471,7 @@ rb_struct_define_under(VALUE outer, const char *name, ...)
|
|||
* "Hello #{name}!"
|
||||
* end
|
||||
* end
|
||||
* Customer.new("Dave", "123 Main").greeting # => "Hello Dave!"
|
||||
* Customer.new("Dave", "123 Main").greeting #=> "Hello Dave!"
|
||||
*
|
||||
* This is the recommended way to customize a struct. Subclassing an
|
||||
* anonymous struct creates an extra anonymous class that will never be used.
|
||||
|
|
@ -476,11 +482,11 @@ rb_struct_define_under(VALUE outer, const char *name, ...)
|
|||
* Passing more parameters than number of attributes will raise
|
||||
* an ArgumentError.
|
||||
*
|
||||
* # Create a structure named by its constant
|
||||
* Customer = Struct.new(:name, :address)
|
||||
* #=> Customer
|
||||
* Customer.new("Dave", "123 Main")
|
||||
* #=> #<struct Customer name="Dave", address="123 Main">
|
||||
* Customer["Dave"]
|
||||
* #=> #<struct Customer name="Dave", address=nil>
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
@ -625,7 +631,7 @@ struct_enum_size(VALUE s, VALUE args, VALUE eobj)
|
|||
/*
|
||||
* call-seq:
|
||||
* struct.each {|obj| block } -> struct
|
||||
* struct.each -> an_enumerator
|
||||
* struct.each -> enumerator
|
||||
*
|
||||
* Yields the value of each struct member in order. If no block is given an
|
||||
* enumerator is returned.
|
||||
|
|
@ -656,7 +662,7 @@ rb_struct_each(VALUE s)
|
|||
/*
|
||||
* call-seq:
|
||||
* struct.each_pair {|sym, obj| block } -> struct
|
||||
* struct.each_pair -> an_enumerator
|
||||
* struct.each_pair -> enumerator
|
||||
*
|
||||
* Yields the name and value of each struct member in order. If no block is
|
||||
* given an enumerator is returned.
|
||||
|
|
@ -747,7 +753,7 @@ inspect_struct(VALUE s, VALUE dummy, int recur)
|
|||
* struct.to_s -> string
|
||||
* struct.inspect -> string
|
||||
*
|
||||
* Describe the contents of this struct in a string.
|
||||
* Returns a description of this struct as a string.
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
@ -871,8 +877,8 @@ invalid_struct_pos(VALUE s, VALUE idx)
|
|||
|
||||
/*
|
||||
* call-seq:
|
||||
* struct[member] -> anObject
|
||||
* struct[index] -> anObject
|
||||
* struct[member] -> object
|
||||
* struct[index] -> object
|
||||
*
|
||||
* Attribute Reference---Returns the value of the given struct +member+ or
|
||||
* the member at the given +index+. Raises NameError if the +member+ does
|
||||
|
|
@ -948,7 +954,7 @@ struct_entry(VALUE s, long n)
|
|||
|
||||
/*
|
||||
* call-seq:
|
||||
* struct.values_at(selector, ...) -> an_array
|
||||
* struct.values_at(selector, ...) -> array
|
||||
*
|
||||
* Returns the struct member values for each +selector+ as an Array. A
|
||||
* +selector+ may be either an Integer offset or a Range of offsets (as in
|
||||
|
|
@ -956,7 +962,7 @@ struct_entry(VALUE s, long n)
|
|||
*
|
||||
* Customer = Struct.new(:name, :address, :zip)
|
||||
* joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
|
||||
* joe.values_at 0, 2 #=> ["Joe Smith", 12345]
|
||||
* joe.values_at(0, 2) #=> ["Joe Smith", 12345]
|
||||
*
|
||||
*/
|
||||
|
||||
|
|
@ -968,8 +974,8 @@ rb_struct_values_at(int argc, VALUE *argv, VALUE s)
|
|||
|
||||
/*
|
||||
* call-seq:
|
||||
* struct.select {|i| block } -> array
|
||||
* struct.select -> an_enumerator
|
||||
* struct.select {|obj| block } -> array
|
||||
* struct.select -> enumerator
|
||||
*
|
||||
* Yields each member value from the struct to the block and returns an Array
|
||||
* containing the member values from the +struct+ for which the given block
|
||||
|
|
@ -977,7 +983,7 @@ rb_struct_values_at(int argc, VALUE *argv, VALUE s)
|
|||
*
|
||||
* Lots = Struct.new(:a, :b, :c, :d, :e, :f)
|
||||
* l = Lots.new(11, 22, 33, 44, 55, 66)
|
||||
* l.select {|v| (v % 2).zero? } #=> [22, 44, 66]
|
||||
* l.select {|v| v.even? } #=> [22, 44, 66]
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
@ -1046,7 +1052,7 @@ rb_struct_equal(VALUE s, VALUE s2)
|
|||
* call-seq:
|
||||
* struct.hash -> integer
|
||||
*
|
||||
* Returns a hash value based on this struct's contents (see Object#hash).
|
||||
* Returns a hash value based on this struct's contents.
|
||||
*
|
||||
* See also Object#hash.
|
||||
*/
|
||||
|
|
@ -1140,11 +1146,12 @@ rb_struct_ptr(VALUE s)
|
|||
* objects by calling +dig+ at each step, returning +nil+ if any
|
||||
* intermediate step is +nil+.
|
||||
*
|
||||
* klass = Struct.new(:a)
|
||||
* o = klass.new(klass.new({b: [1, 2, 3]}))
|
||||
* Foo = Struct.new(:a)
|
||||
* f = Foo.new(Foo.new({b: [1, 2, 3]}))
|
||||
*
|
||||
* o.dig(:a, :a, :b, 0) #=> 1
|
||||
* o.dig(:b, 0) #=> nil
|
||||
* f.dig(:a, :a, :b, 0) # => 1
|
||||
* f.dig(:b, 0) # => nil
|
||||
* f.dig(:a, :a, :b, :c) # TypeError: no implicit conversion of Symbol into Integer
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
@ -1180,7 +1187,7 @@ rb_struct_dig(int argc, VALUE *argv, VALUE self)
|
|||
* See Struct::new for further examples of creating struct subclasses and
|
||||
* instances.
|
||||
*
|
||||
* In the method descriptions that follow a "member" parameter refers to a
|
||||
* In the method descriptions that follow, a "member" parameter refers to a
|
||||
* struct member which is either a quoted string (<code>"name"</code>) or a
|
||||
* Symbol (<code>:name</code>).
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
#define RUBY_VERSION "2.4.0"
|
||||
#define RUBY_RELEASE_DATE "2017-03-13"
|
||||
#define RUBY_PATCHLEVEL 73
|
||||
#define RUBY_PATCHLEVEL 74
|
||||
|
||||
#define RUBY_RELEASE_YEAR 2017
|
||||
#define RUBY_RELEASE_MONTH 3
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue