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

4 files changed, 52 insertions, 43 deletions

diff --git a/hash.c b/hash.c
index c90814b2ee..4a28b86bae 100644
--- a/hash.c
+++ b/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
diff --git a/lib/fileutils.rb b/lib/fileutils.rb
index 506b62f825..5d769ac32b 100644
--- a/lib/fileutils.rb
+++ b/lib/fileutils.rb
@@ -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)
diff --git a/struct.c b/struct.c
index 9289338a16..7cf7def65d 100644
--- a/struct.c
+++ b/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>).
  */
diff --git a/version.h b/version.h
index 2e1e818bf3..5f944711b9 100644
--- a/version.h
+++ b/version.h
@@ -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