documentation for Open3, Ping

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)
 #
-# 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:
 #
+#   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| ... }
+#
 
 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"
 
-#= 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().
 #
-# This module contains routines to test for the reachability of remote hosts.
-# Currently the only routine implemented is pingecho(). 
-#
-# pingecho() uses a TCP echo (_not_ an ICMP echo) to determine if the
+# Ping.pingecho uses a TCP echo (not an ICMP echo) to determine if the
 # remote host is reachable. This is usually adequate to tell that a remote
-# host is available to rsh(1), ftp(1), or telnet(1) to.
+# host is available to telnet, ftp, or ssh to.
+#
+# Warning: Ping.pingecho may block for a long time if DNS resolution is
+# slow. Requiring 'resolv-replace' allows non-blocking name resolution.
 #
-#= WARNING
+# Usage:
+# 
+#   require 'ping'
 #
-# pingecho() may block for a long period if name resolution is slow.  Require
-# 'resolv-replace' to use non-blocking name resolution.
+#   puts "'jimmy' is alive and kicking" if Ping.pingecho('jimmy', 10)
 #
@@ -29,5 +32,13 @@ module Ping
 
-  # return true if we can open a connection to the hostname or IP address
-  # +host+ on port +service+ (which defaults to the "echo" port) waiting up to
-  # +timeout+ seconds.
+  # 
+  # Return true if we can open a connection to the hostname or IP address
+  # +host+ on port +service+ (which defaults to the "echo" port) waiting up
+  # to +timeout+ seconds.
+  #
+  # Example:
+  #
+  #   require 'ping'
+  #
+  #   Ping.pingecho "google.com", 10, 80
+  #
   def pingecho(host, timeout=5, service="echo")