lib/open3.rb: tweaked grammar in comments

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@43554 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 45 insertions, 45 deletions

diff --git a/lib/open3.rb b/lib/open3.rb
index 1ee014d8a9..72fd6bb52f 100644
--- a/lib/open3.rb
+++ b/lib/open3.rb
@@ -9,29 +9,29 @@
 #
 
 #
-# Open3 grants you access to stdin, stdout, stderr and a thread to wait the
+# Open3 grants you access to stdin, stdout, stderr and a thread to wait for the
 # child process when running another program.
 # You can specify various attributes, redirections, current directory, etc., of
-# the program as Process.spawn.
+# the program in the same way as for Process.spawn.
 #
 # - Open3.popen3 : pipes for stdin, stdout, stderr
 # - Open3.popen2 : pipes for stdin, stdout
 # - Open3.popen2e : pipes for stdin, merged stdout and stderr
-# - Open3.capture3 : give a string for stdin.  get strings for stdout, stderr
-# - Open3.capture2 : give a string for stdin.  get a string for stdout
-# - Open3.capture2e : give a string for stdin.  get a string for merged stdout and stderr
+# - Open3.capture3 : give a string for stdin; get strings for stdout, stderr
+# - Open3.capture2 : give a string for stdin; get a string for stdout
+# - Open3.capture2e : give a string for stdin; get a string for merged stdout and stderr
 # - Open3.pipeline_rw : pipes for first stdin and last stdout of a pipeline
 # - Open3.pipeline_r : pipe for last stdout of a pipeline
 # - Open3.pipeline_w : pipe for first stdin of a pipeline
-# - Open3.pipeline_start : run a pipeline and don't wait
-# - Open3.pipeline : run a pipeline and wait
+# - Open3.pipeline_start : run a pipeline without waiting
+# - Open3.pipeline : run a pipeline and wait for its completion
 #
 
 module Open3
 
   # Open stdin, stdout, and stderr streams and start external executable.
-  # In addition, a thread for waiting the started process is noticed.
-  # The thread has a pid method and thread variable :pid which is the pid of
+  # In addition, a thread to wait for the started process is created.
+  # The thread has a pid method and a thread variable :pid which is the pid of
   # the started process.
   #
   # Block form:
@@ -45,15 +45,15 @@ module Open3
   # Non-block form:
   #
   #   stdin, stdout, stderr, wait_thr = Open3.popen3([env,] cmd... [, opts])
-  #   pid = wait_thr[:pid]  # pid of the started process.
+  #   pid = wait_thr[:pid]  # pid of the started process
   #   ...
   #   stdin.close  # stdin, stdout and stderr should be closed explicitly in this form.
   #   stdout.close
   #   stderr.close
   #   exit_status = wait_thr.value  # Process::Status object returned.
   #
-  # The parameters +cmd...+ is passed to Process.spawn.
-  # So a commandline string and list of argument strings can be accepted as follows.
+  # The parameters env, cmd, and opts are passed to Process.spawn.
+  # A commandline string and a list of argument strings can be accepted as follows:
   #
   #   Open3.popen3("echo abc") {|i, o, e, t| ... }
   #   Open3.popen3("echo", "abc") {|i, o, e, t| ... }
@@ -65,19 +65,19 @@ module Open3
   #     p o.read.chomp #=> "/"
   #   }
   #
-  # wait_thr.value waits the termination of the process.
-  # The block form also waits the process when it returns.
+  # wait_thr.value waits for the termination of the process.
+  # The block form also waits for the process when it returns.
   #
-  # Closing stdin, stdout and stderr does not wait the process.
+  # Closing stdin, stdout and stderr does not wait for the process to complete.
   #
   # You should be careful to avoid deadlocks.
-  # Since pipes are fixed length buffer,
+  # Since pipes are fixed length buffers,
   # Open3.popen3("prog") {|i, o, e, t| o.read } deadlocks if
-  # the program generates many output on stderr.
-  # You should be read stdout and stderr simultaneously (using thread or IO.select).
-  # However if you don't need stderr output, Open3.popen2 can be used.
+  # the program generates too much output on stderr.
+  # You should read stdout and stderr simultaneously (using threads or IO.select).
+  # However, if you don't need stderr output, you can use Open3.popen2.
   # If merged stdout and stderr output is not a problem, you can use Open3.popen2e.
-  # If you really needs stdout and stderr output as separate strings, you can consider Open3.capture3.
+  # If you really need stdout and stderr output as separate strings, you can consider Open3.capture3.
   #
   def popen3(*cmd, &block)
     if Hash === cmd.last
@@ -100,7 +100,7 @@ module Open3
   end
   module_function :popen3
 
-  # Open3.popen2 is similer to Open3.popen3 except it doesn't make a pipe for
+  # Open3.popen2 is similar to Open3.popen3 except that it doesn't create a pipe for
   # the standard error stream.
   #
   # Block form:
@@ -158,7 +158,7 @@ module Open3
   end
   module_function :popen2
 
-  # Open3.popen2e is similer to Open3.popen3 except it merges
+  # Open3.popen2e is similar to Open3.popen3 except that it merges
   # the standard output stream and the standard error stream.
   #
   # Block form:
@@ -238,7 +238,7 @@ module Open3
   #
   # If opts[:binmode] is true, internal pipes are set to binary mode.
   #
-  # Example:
+  # Examples:
   #
   #   # dot is a command of graphviz.
   #   graph = <<'End'
@@ -246,7 +246,7 @@ module Open3
   #       a -> b
   #     }
   #   End
-  #   layouted_graph, dot_log = Open3.capture3("dot -v", :stdin_data=>graph)
+  #   drawn_graph, dot_log = Open3.capture3("dot -v", :stdin_data=>graph)
   #
   #   o, e, s = Open3.capture3("echo abc; sort >&2", :stdin_data=>"foo\nbar\nbaz\n")
   #   p o #=> "abc\n"
@@ -254,11 +254,11 @@ module Open3
   #   p s #=> #<Process::Status: pid 32682 exit 0>
   #
   #   # generate a thumnail image using the convert command of ImageMagick.
-  #   # However, if the image stored really in a file,
+  #   # However, if the image is really stored in a file,
   #   # system("convert", "-thumbnail", "80", "png:#{filename}", "png:-") is better
-  #   # because memory consumption.
-  #   # But if the image is stored in a DB or generated by gnuplot Open3.capture2 example,
-  #   # Open3.capture3 is considerable.
+  #   # because of reduced memory consumption.
+  #   # But if the image is stored in a DB or generated by the gnuplot Open3.capture2 example,
+  #   # Open3.capture3 should be considered.
   #   #
   #   image = File.read("/usr/share/openclipart/png/animals/mammals/sheep-md-v0.1.png", :binmode=>true)
   #   thumnail, err, s = Open3.capture3("convert -thumbnail 80 png:- png:-", :stdin_data=>image, :binmode=>true)
@@ -383,7 +383,7 @@ module Open3
   module_function :capture2e
 
   # Open3.pipeline_rw starts a list of commands as a pipeline with pipes
-  # which connects stdin of the first command and stdout of the last command.
+  # which connect to stdin of the first command and stdout of the last command.
   #
   #   Open3.pipeline_rw(cmd1, cmd2, ... [, opts]) {|first_stdin, last_stdout, wait_threads|
   #     ...
@@ -403,15 +403,15 @@ module Open3
   #     [env, cmdname, arg1, ..., opts]          command name and one or more arguments (no shell)
   #     [env, [cmdname, argv0], arg1, ..., opts] command name and arguments including argv[0] (no shell)
   #
-  #   Note that env and opts are optional, as Process.spawn.
+  #   Note that env and opts are optional, as for Process.spawn.
   #
-  # The option to pass Process.spawn is constructed by merging
-  # +opts+, the last hash element of the array and
-  # specification for the pipe between each commands.
+  # The options to pass to Process.spawn are constructed by merging
+  # +opts+, the last hash element of the array, and
+  # specifications for the pipes between each of the commands.
   #
   # Example:
   #
-  #   Open3.pipeline_rw("tr -dc A-Za-z", "wc -c") {|i,o,ts|
+  #   Open3.pipeline_rw("tr -dc A-Za-z", "wc -c") {|i, o, ts|
   #     i.puts "All persons more than a mile high to leave the court."
   #     i.close
   #     p o.gets #=> "42\n"
@@ -443,7 +443,7 @@ module Open3
   module_function :pipeline_rw
 
   # Open3.pipeline_r starts a list of commands as a pipeline with a pipe
-  # which connects stdout of the last command.
+  # which connects to stdout of the last command.
   #
   #   Open3.pipeline_r(cmd1, cmd2, ... [, opts]) {|last_stdout, wait_threads|
   #     ...
@@ -462,7 +462,7 @@ module Open3
   #     [env, cmdname, arg1, ..., opts]          command name and one or more arguments (no shell)
   #     [env, [cmdname, argv0], arg1, ..., opts] command name and arguments including argv[0] (no shell)
   #
-  #   Note that env and opts are optional, as Process.spawn.
+  #   Note that env and opts are optional, as for Process.spawn.
   #
   # Example:
   #
@@ -495,7 +495,7 @@ module Open3
   module_function :pipeline_r
 
   # Open3.pipeline_w starts a list of commands as a pipeline with a pipe
-  # which connects stdin of the first command.
+  # which connects to stdin of the first command.
   #
   #   Open3.pipeline_w(cmd1, cmd2, ... [, opts]) {|first_stdin, wait_threads|
   #     ...
@@ -514,7 +514,7 @@ module Open3
   #     [env, cmdname, arg1, ..., opts]          command name and one or more arguments (no shell)
   #     [env, [cmdname, argv0], arg1, ..., opts] command name and arguments including argv[0] (no shell)
   #
-  #   Note that env and opts are optional, as Process.spawn.
+  #   Note that env and opts are optional, as for Process.spawn.
   #
   # Example:
   #
@@ -538,7 +538,7 @@ module Open3
   module_function :pipeline_w
 
   # Open3.pipeline_start starts a list of commands as a pipeline.
-  # No pipe made for stdin of the first command and
+  # No pipes are created for stdin of the first command and
   # stdout of the last command.
   #
   #   Open3.pipeline_start(cmd1, cmd2, ... [, opts]) {|wait_threads|
@@ -557,11 +557,11 @@ module Open3
   #     [env, cmdname, arg1, ..., opts]          command name and one or more arguments (no shell)
   #     [env, [cmdname, argv0], arg1, ..., opts] command name and arguments including argv[0] (no shell)
   #
-  #   Note that env and opts are optional, as Process.spawn.
+  #   Note that env and opts are optional, as for Process.spawn.
   #
   # Example:
   #
-  #   # run xeyes in 10 seconds.
+  #   # Run xeyes in 10 seconds.
   #   Open3.pipeline_start("xeyes") {|ts|
   #     sleep 10
   #     t = ts[0]
@@ -569,8 +569,8 @@ module Open3
   #     p t.value #=> #<Process::Status: pid 911 SIGTERM (signal 15)>
   #   }
   #
-  #   # convert pdf to ps and send it to a printer.
-  #   # collect error message of pdftops and lpr.
+  #   # Convert pdf to ps and send it to a printer.
+  #   # Collect error message of pdftops and lpr.
   #   pdf_file = "paper.pdf"
   #   printer = "printer-name"
   #   err_r, err_w = IO.pipe
@@ -598,8 +598,8 @@ module Open3
   module_function :pipeline_start
 
   # Open3.pipeline starts a list of commands as a pipeline.
-  # It waits the finish of the commands.
-  # No pipe made for stdin of the first command and
+  # It waits for the completion of the commands.
+  # No pipes are created for stdin of the first command and
   # stdout of the last command.
   #
   #   status_list = Open3.pipeline(cmd1, cmd2, ... [, opts])