Re: documentation for Open3, Ping

On 10/15/06, Eric Hodel <[email protected]> wrote:
> On Oct 7, 2006, at 4:08 PM, Konrad Meyer wrote:
> > If the formatting and whatnot of ParseDate is ok, I have patches for
> > Open3 and Ping (yes, I know they're simple) ready. See attached.
>
> Index: open3.rb
> ===================================================================
> RCS file: /src/ruby/lib/open3.rb,v
> retrieving revision 1.13
> diff -p -u -1 -r1.13 open3.rb
> --- open3.rb    4 Aug 2006 18:05:40 -0000       1.13
> +++ open3.rb    7 Oct 2006 23:05:03 -0000
> @@ -1,13 +1,16 @@
> -# open3.rb: Spawn a program like popen, but with stderr, too. You
> might also
> -# want to use this if you want to bypass the shell. (By passing
> multiple args,
> -# which IO#popen does not allow)
>
> The "You might also..." sentence should remain.  (I think IO#popen
> should reference #popen3 as well.)

OK.

> #
> -# Usage:
> +# = open3.rb: Popen, but with stderr, too
> #
> -#   require "open3"
> -#
> -#   stdin, stdout, stderr = Open3.popen3('nroff -man')
> +# Author:: Yukihiro Matsumoto
> +# Documentation:: Konrad Meyer
> +#
> +# Open3 gives you access to stdin, stdout, and stderr when running
> other
> +# programs.
> +#
> +
> #
> -# or:
> +# Open3 grants you access to stdin, stdout, and stderr when running
> another
> +# program. Example:
>
> I like "gives you".

Agreed.

>
> +#   require "open3"
> #   include Open3
> @@ -16,12 +19,28 @@
> #
> -# popen3 can also take a block which will receive stdin, stdout and
> stderr as
> -# parameters.  This ensures stdin, stdout and stderr are closed once
> the block
> -# exits.
> +# Open3.popen3 can also take a block which will receive stdin,
> stdout and
> +# stderr as parameters.  This ensures stdin, stdout and stderr are
> closed
> +# once the block exits. Example:
> #
> -# Such as:
> +#   require "open3"
> #
> #   Open3.popen3('nroff -man') { |stdin, stdout, stderr| ... }
> +#
>
> I think this should be moved to the #popen3 method.  I like class/
> module level being overview and general usage and method being
> specific usage.  This way you don't have to go back and forth so much
> to figure out how a something is supposed to be used or work.
>

Alright, makes enough sense to me.

> module Open3
> -  #[stdin, stdout, stderr] = popen3(command);
> +  #
> +  # Open stdin, stdout, and stderr streams and start external
> executable.
> +  # Non-block form:
> +  #
> +  #   require 'open3'
> +  #
> +  #   [stdin, stdout, stderr] = Open3.popen3(cmd)
> +  #
> +  # Block form:
> +  #
> +  #   require 'open3'
> +  #
> +  #   Open3.popen3(cmd) { |stdin, stdout, stderr| ... }
> +  #
> +  # The parameter +cmd+ is passed directly to Kernel#exec.
> +  #
>     def popen3(*cmd)
> Index: ping.rb

New open3.rb.patch.

-- 
Konrad Meyer

Index: open3.rb
===================================================================
RCS file: /src/ruby/lib/open3.rb,v
retrieving revision 1.13
diff -p -u -1 -r1.13 open3.rb
--- open3.rb	4 Aug 2006 18:05:40 -0000	1.13
+++ open3.rb	16 Oct 2006 04:49:14 -0000
@@ -1,27 +1,37 @@
-# open3.rb: Spawn a program like popen, but with stderr, too. You might also
-# want to use this if you want to bypass the shell. (By passing multiple args,
-# which IO#popen does not allow)
 #
-# Usage:
+# = open3.rb: Popen, but with stderr, too
 #
-#   require "open3"
-#   
-#   stdin, stdout, stderr = Open3.popen3('nroff -man')
+# Author:: Yukihiro Matsumoto
 #
-# or:
+# Open3 gives you access to stdin, stdout, and stderr when running other
+# programs. You might also want to use this if you want to bypass the shell
+# (by passing multiple args, which IO#popen does not allow).
 #
-#   include Open3
-#   
-#   stdin, stdout, stderr = popen3('nroff -man')
+
 #
-# popen3 can also take a block which will receive stdin, stdout and stderr as
-# parameters.  This ensures stdin, stdout and stderr are closed once the block
-# exits.
+# Open3 gives you access to stdin, stdout, and stderr when running another
+# program. Example:
 #
-# Such as:
+#   require "open3"
+#   
+#   stdin, stdout, stderr = Open3.popen3('nroff -man')
 #
-#   Open3.popen3('nroff -man') { |stdin, stdout, stderr| ... }
 
 module Open3
-  #[stdin, stdout, stderr] = popen3(command);
+  # 
+  # Open stdin, stdout, and stderr streams and start external executable.
+  # Non-block form:
+  #   
+  #   require 'open3'
+  #
+  #   [stdin, stdout, stderr] = Open3.popen3(cmd)
+  #
+  # Open3.popen3 can also take a block which will receive stdin, stdout and
+  # stderr as parameters.  This ensures stdin, stdout and stderr are closed
+  # once the block exits. Example:
+  #
+  #   Open3.popen3(cmd) { |stdin, stdout, stderr| ... }
+  #
+  # The parameter +cmd+ is passed directly to Kernel#exec.
+  #
   def popen3(*cmd)