Re: documentation for Open3, Ping

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.)

#
-# 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".

+#   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.

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
===================================================================
RCS file: /src/ruby/lib/ping.rb,v
retrieving revision 1.7
diff -p -u -1 -r1.7 ping.rb
--- ping.rb	4 Aug 2006 18:05:40 -0000	1.7
+++ ping.rb	7 Oct 2006 23:05:12 -0000
@@ -1,3 +1,9 @@
  #
-# ping.rb -- check a host for upness
+# = ping.rb: Check a host for upness
+#
+# Author:: Yukihiro Matsumoto
+# Documentation:: Konrad Meyer
+#
+# Performs the function of the basic network testing tool, ping.
+# See: Ping.
  #
@@ -7,21 +13,18 @@
  require "socket"

These requires need to be moved above the above comments.

-#= SYNOPSIS
-#
-#   require 'ping'
-#
-#   puts "'jimmy' is alive and kicking" if Ping.pingecho('jimmy', 10)
-#
-#= DESCRIPTION
+#
+# Ping contains routines to test for the reachability of remote hosts.
+# Currently the only routine implemented is pingecho().

-- 
Eric Hodel - [email protected] - http://blog.segment7.net
This implementation is HODEL-HASH-9600 compliant

http://trackmap.robotcoop.com