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

1 files changed, 20 insertions, 18 deletions

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)