[DOC] Rdoc tweaks

lib/open3.rb

@@ -72,11 +72,11 @@
 # Each of the methods above accepts:
 #
 # - An optional hash of environment variable names and values;
-#   see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#Execution+Environment].
+#   see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
 # - A required string argument that is a +command_line+ or +exe_path+;
-#   see {Argument command_line or exe_path}[https://docs.ruby-lang.org/en/master/Process.html#Argument+command_line+or+exe_path].
+#   see {Argument command_line or exe_path}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Argument+command_line+or+exe_path].
 # - An optional hash of execution options;
-#   see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#Execution+Options].
+#   see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
 #
 module Open3
 
@@ -135,13 +135,18 @@ module Open3
   #
   # Like Process.spawn, this method has potential security vulnerabilities
   # if called with untrusted input;
-  # see {Command Injection}[rdoc-ref:command_injection.rdoc].
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
   #
   # Unlike Process.spawn, this method waits for the child process to exit
   # before returning, so the caller need not do so.
   #
-  # Argument +options+ is a hash of options for the new process;
-  # see {Execution Options}[rdoc-ref:Process@Execution+Options].
+  # If the first argument is a hash, it becomes leading argument +env+
+  # in the call to Process.spawn;
+  # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
+  #
+  # If the last argument is a hash, it becomes trailing argument +options+
+  # in the call to Process.spawn;
+  # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
   #
   # The single required argument is one of the following:
   #
@@ -283,13 +288,18 @@ def popen3(*cmd, &block)
   #
   # Like Process.spawn, this method has potential security vulnerabilities
   # if called with untrusted input;
-  # see {Command Injection}[rdoc-ref:command_injection.rdoc].
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
   #
   # Unlike Process.spawn, this method waits for the child process to exit
   # before returning, so the caller need not do so.
   #
-  # Argument +options+ is a hash of options for the new process;
-  # see {Execution Options}[rdoc-ref:Process@Execution+Options].
+  # If the first argument is a hash, it becomes leading argument +env+
+  # in the call to Process.spawn;
+  # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
+  #
+  # If the last argument is a hash, it becomes trailing argument +options+
+  # in the call to Process.spawn;
+  # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
   #
   # The single required argument is one of the following:
   #
@@ -422,13 +432,18 @@ def popen2(*cmd, &block)
   #
   # Like Process.spawn, this method has potential security vulnerabilities
   # if called with untrusted input;
-  # see {Command Injection}[rdoc-ref:command_injection.rdoc].
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
   #
   # Unlike Process.spawn, this method waits for the child process to exit
   # before returning, so the caller need not do so.
   #
-  # Argument +options+ is a hash of options for the new process;
-  # see {Execution Options}[rdoc-ref:Process@Execution+Options].
+  # If the first argument is a hash, it becomes leading argument +env+
+  # in the call to Process.spawn;
+  # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
+  #
+  # If the last argument is a hash, it becomes trailing argument +options+
+  # in the call to Process.spawn;
+  # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
   #
   # The single required argument is one of the following:
   #
@@ -555,15 +570,20 @@ class << self
   #
   # Like Process.spawn, this method has potential security vulnerabilities
   # if called with untrusted input;
-  # see {Command Injection}[rdoc-ref:command_injection.rdoc].
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
   #
   # Unlike Process.spawn, this method waits for the child process to exit
   # before returning, so the caller need not do so.
   #
-  # Argument +options+ is a hash of options for the new process;
-  # see {Execution Options}[rdoc-ref:Process@Execution+Options].
+  # If the first argument is a hash, it becomes leading argument +env+
+  # in the call to Open3.popen3;
+  # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
   #
-  # The hash +options+ is passed to method Open3.popen3;
+  # If the last argument is a hash, it becomes trailing argument +options+
+  # in the call to Open3.popen3;
+  # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
+  #
+  # The hash +options+ is given;
   # two options have local effect in method Open3.capture3:
   #
   # - If entry <tt>options[:stdin_data]</tt> exists, the entry is removed
@@ -572,7 +592,7 @@ class << self
   #     Open3.capture3('tee', stdin_data: 'Foo')
   #     # => ["Foo", "", #<Process::Status: pid 2319575 exit 0>]
   #
-  # - If entry <tt>options[:binmode]</tt> exists, the entry is removed
+  # - If entry <tt>options[:binmode]</tt> exists, the entry is removed and
   #   the internal streams are set to binary mode.
   #
   # The single required argument is one of the following:
@@ -676,15 +696,20 @@ def capture3(*cmd)
   #
   # Like Process.spawn, this method has potential security vulnerabilities
   # if called with untrusted input;
-  # see {Command Injection}[rdoc-ref:command_injection.rdoc].
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
   #
   # Unlike Process.spawn, this method waits for the child process to exit
   # before returning, so the caller need not do so.
   #
-  # Argument +options+ is a hash of options for the new process;
-  # see {Execution Options}[rdoc-ref:Process@Execution+Options].
+  # If the first argument is a hash, it becomes leading argument +env+
+  # in the call to Open3.popen3;
+  # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
   #
-  # The hash +options+ is passed to method Open3.popen3;
+  # If the last argument is a hash, it becomes trailing argument +options+
+  # in the call to Open3.popen3;
+  # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
+  #
+  # The hash +options+ is given;
   # two options have local effect in method Open3.capture2:
   #
   # - If entry <tt>options[:stdin_data]</tt> exists, the entry is removed
@@ -694,6 +719,7 @@ def capture3(*cmd)
   #
   #     # => ["Foo", #<Process::Status: pid 2326087 exit 0>]
   #
+  # - If entry <tt>options[:binmode]</tt> exists, the entry is removed and
   #   the internal streams are set to binary mode.
   #
   # The single required argument is one of the following:
@@ -798,15 +824,20 @@ def capture2(*cmd)
   #
   # Like Process.spawn, this method has potential security vulnerabilities
   # if called with untrusted input;
-  # see {Command Injection}[rdoc-ref:command_injection.rdoc].
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
   #
   # Unlike Process.spawn, this method waits for the child process to exit
   # before returning, so the caller need not do so.
   #
-  # Argument +options+ is a hash of options for the new process;
-  # see {Execution Options}[rdoc-ref:Process@Execution+Options].
+  # If the first argument is a hash, it becomes leading argument +env+
+  # in the call to Open3.popen3;
+  # see {Execution Environment}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Environment].
   #
-  # The hash +options+ is passed to method Open3.popen3;
+  # If the last argument is a hash, it becomes trailing argument +options+
+  # in the call to Open3.popen3;
+  # see {Execution Options}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options].
+  #
+  # The hash +options+ is given;
   # two options have local effect in method Open3.capture2e:
   #
   # - If entry <tt>options[:stdin_data]</tt> exists, the entry is removed
@@ -815,6 +846,7 @@ def capture2(*cmd)
   #     Open3.capture2e('tee', stdin_data: 'Foo')
   #     # => ["Foo", #<Process::Status: pid 2371732 exit 0>]
   #
+  # - If entry <tt>options[:binmode]</tt> exists, the entry is removed and
   #   the internal streams are set to binary mode.
   #
   # The single required argument is one of the following:
@@ -959,7 +991,7 @@ def capture2e(*cmd)
   #
   # Like Process.spawn, this method has potential security vulnerabilities
   # if called with untrusted input;
-  # see {Command Injection}[rdoc-ref:command_injection.rdoc].
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
   #
   # If the first argument is a hash, it becomes leading argument +env+
   # in each call to Process.spawn;
@@ -977,6 +1009,8 @@ def capture2e(*cmd)
   # - An array containing a +command_line+ or an +exe_path+,
   #   along with zero or more string arguments for the command.
   #
+  # See {Argument command_line or exe_path}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Argument+command_line+or+exe_path].
+  #
   def pipeline_rw(*cmds, &block)
     if Hash === cmds.last
       opts = cmds.pop.dup
@@ -1047,7 +1081,7 @@ def pipeline_rw(*cmds, &block)
   #
   # Like Process.spawn, this method has potential security vulnerabilities
   # if called with untrusted input;
-  # see {Command Injection}[rdoc-ref:command_injection.rdoc].
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
   #
   # If the first argument is a hash, it becomes leading argument +env+
   # in each call to Process.spawn;
@@ -1065,6 +1099,8 @@ def pipeline_rw(*cmds, &block)
   # - An array containing a +command_line+ or an +exe_path+,
   #   along with zero or more string arguments for the command.
   #
+  # See {Argument command_line or exe_path}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Argument+command_line+or+exe_path].
+  #
   def pipeline_r(*cmds, &block)
     if Hash === cmds.last
       opts = cmds.pop.dup
@@ -1136,7 +1172,7 @@ def pipeline_r(*cmds, &block)
   #
   # Like Process.spawn, this method has potential security vulnerabilities
   # if called with untrusted input;
-  # see {Command Injection}[rdoc-ref:command_injection.rdoc].
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
   #
   # If the first argument is a hash, it becomes leading argument +env+
   # in each call to Process.spawn;
@@ -1154,6 +1190,8 @@ def pipeline_r(*cmds, &block)
   # - An array containing a +command_line+ or an +exe_path+,
   #   along with zero or more string arguments for the command.
   #
+  # See {Argument command_line or exe_path}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Argument+command_line+or+exe_path].
+  #
   def pipeline_w(*cmds, &block)
     if Hash === cmds.last
       opts = cmds.pop.dup
@@ -1211,7 +1249,7 @@ def pipeline_w(*cmds, &block)
   #
   # Like Process.spawn, this method has potential security vulnerabilities
   # if called with untrusted input;
-  # see {Command Injection}[rdoc-ref:command_injection.rdoc].
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
   #
   # If the first argument is a hash, it becomes leading argument +env+
   # in each call to Process.spawn;
@@ -1229,6 +1267,8 @@ def pipeline_w(*cmds, &block)
   # - An array containing a +command_line+ or an +exe_path+,
   #   along with zero or more string arguments for the command.
   #
+  # See {Argument command_line or exe_path}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Argument+command_line+or+exe_path].
+  #
   def pipeline_start(*cmds, &block)
     if Hash === cmds.last
       opts = cmds.pop.dup
@@ -1271,7 +1311,7 @@ def pipeline_start(*cmds, &block)
   #
   # Like Process.spawn, this method has potential security vulnerabilities
   # if called with untrusted input;
-  # see {Command Injection}[rdoc-ref:command_injection.rdoc].
+  # see {Command Injection}[https://docs.ruby-lang.org/en/master/command_injection_rdoc.html#label-Command+Injection].
   #
   # If the first argument is a hash, it becomes leading argument +env+
   # in each call to Process.spawn;
@@ -1289,6 +1329,8 @@ def pipeline_start(*cmds, &block)
   # - An array containing a +command_line+ or an +exe_path+,
   #   along with zero or more string arguments for the command.
   #
+  # See {Argument command_line or exe_path}[https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Argument+command_line+or+exe_path].
+  #
   def pipeline(*cmds)
     if Hash === cmds.last
       opts = cmds.pop.dup