ruby-changes:45845
From: naruse <ko1@a...>
Date: Mon, 13 Mar 2017 01:20:08 +0900 (JST)
Subject: [ruby-changes:45845] naruse:r57918 (ruby_2_4): merge revision(s) 57751, 57753, 57755:
naruse 2017-03-13 01:20:03 +0900 (Mon, 13 Mar 2017) New Revision: 57918 https://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=57918 Log: 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. Modified directories: branches/ruby_2_4/ Modified files: branches/ruby_2_4/hash.c branches/ruby_2_4/lib/fileutils.rb branches/ruby_2_4/struct.c branches/ruby_2_4/version.h Index: ruby_2_4/lib/fileutils.rb =================================================================== --- ruby_2_4/lib/fileutils.rb (revision 57917) +++ ruby_2_4/lib/fileutils.rb (revision 57918) @@ -16,7 +16,7 @@ https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/fileutils.rb#L16 # 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 @@ https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/fileutils.rb#L38 # 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 https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/fileutils.rb#L112 # 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 https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/fileutils.rb#L144 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 https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/fileutils.rb#L175 # 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 https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/fileutils.rb#L326 # # 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 https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/fileutils.rb#L510 # # 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 https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/fileutils.rb#L526 # 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 https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/fileutils.rb#L556 # # 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 https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/fileutils.rb#L576 # (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 https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/fileutils.rb#L596 # # 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 https://github.com/ruby/ruby/blob/trunk/ruby_2_4/lib/fileutils.rb#L801 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) Index: ruby_2_4/struct.c =================================================================== --- ruby_2_4/struct.c (revision 57917) +++ ruby_2_4/struct.c (revision 57918) @@ -436,10 +436,10 @@ rb_struct_define_under(VALUE outer, cons https://github.com/ruby/ruby/blob/trunk/ruby_2_4/struct.c#L436 /* * 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, cons https://github.com/ruby/ruby/blob/trunk/ruby_2_4/struct.c#L457 * 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, cons https://github.com/ruby/ruby/blob/trunk/ruby_2_4/struct.c#L471 * "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, cons https://github.com/ruby/ruby/blob/trunk/ruby_2_4/struct.c#L482 * 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, VA https://github.com/ruby/ruby/blob/trunk/ruby_2_4/struct.c#L631 /* * 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) https://github.com/ruby/ruby/blob/trunk/ruby_2_4/struct.c#L662 /* * 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 https://github.com/ruby/ruby/blob/trunk/ruby_2_4/struct.c#L753 * 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) https://github.com/ruby/ruby/blob/trunk/ruby_2_4/struct.c#L877 /* * 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) https://github.com/ruby/ruby/blob/trunk/ruby_2_4/struct.c#L954 /* * 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) https://github.com/ruby/ruby/blob/trunk/ruby_2_4/struct.c#L962 * * 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 *arg https://github.com/ruby/ruby/blob/trunk/ruby_2_4/struct.c#L974 /* * 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 *arg https://github.com/ruby/ruby/blob/trunk/ruby_2_4/struct.c#L983 * * 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) https://github.com/ruby/ruby/blob/trunk/ruby_2_4/struct.c#L1052 * 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) https://github.com/ruby/ruby/blob/trunk/ruby_2_4/struct.c#L1146 * 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, VAL https://github.com/ruby/ruby/blob/trunk/ruby_2_4/struct.c#L1187 * 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>). */ Index: ruby_2_4/hash.c =================================================================== --- ruby_2_4/hash.c (revision 57917) +++ ruby_2_4/hash.c (revision 57918) @@ -4375,7 +4375,7 @@ env_update(VALUE env, VALUE hash) https://github.com/ruby/ruby/blob/trunk/ruby_2_4/hash.c#L4375 * 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 Index: ruby_2_4/version.h =================================================================== --- ruby_2_4/version.h (revision 57917) +++ ruby_2_4/version.h (revision 57918) @@ -1,6 +1,6 @@ https://github.com/ruby/ruby/blob/trunk/ruby_2_4/version.h#L1 #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 Property changes on: ruby_2_4 ___________________________________________________________________ Modified: svn:mergeinfo Merged /trunk:r57751,57753,57755 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/