* lib/parsedate.rb: documentation patch from Konrad Meyer

  <konrad.meyer@gmail.com>.  [ruby-doc:1238]

* lib/open3.rb, lib/ping.rb: ditto.


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

3 files changed, 103 insertions, 35 deletions

diff --git a/lib/open3.rb b/lib/open3.rb
index f722252b1c..c4dacc9473 100644
--- a/lib/open3.rb
+++ b/lib/open3.rb
@@ -1,29 +1,48 @@
-# 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
 #   
 #   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.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)
     pw = IO::pipe   # pipe[0] for read, pipe[1] for write
     pr = IO::pipe
diff --git a/lib/parsedate.rb b/lib/parsedate.rb
index 405ab46907..b52a79ba47 100644
--- a/lib/parsedate.rb
+++ b/lib/parsedate.rb
@@ -1,10 +1,48 @@
-# parsedate.rb: Written by Tadayoshi Funaba 2001, 2002
-# $Id: parsedate.rb,v 2.6 2002-05-14 07:43:18+09 tadf Exp $
+#
+# = parsedate.rb: Parses dates
+#
+# Author:: Tadayoshi Funaba
+# Documentation:: Konrad Meyer
+#
+# ParseDate munches on a date and turns it into an array of values.
+#
+
+#
+# ParseDate converts a date into an array of values.
+# For example:
+#
+#   require 'parsedate'
+#
+#   ParseDate.parsedate "Tuesday, July 6th, 2007, 18:35:20 UTC"
+#   # => [2007, 7, 6, 18, 35, 20, "UTC", 2]
+#
+# The order is of the form [year, month, day of month, hour, minute, second,
+# timezone, day of the week].
 
 require 'date/format'
 
 module ParseDate
-
+  #
+  # Parse a string representation of a date into values.
+  # For example:
+  #
+  #   require 'parsedate'
+  #
+  #   ParseDate.parsedate "Tuesday, July 5th, 2007, 18:35:20 UTC"
+  #   # => [2007, 7, 5, 18, 35, 20, "UTC", 2]
+  #
+  # The order is of the form [year, month, day of month, hour, minute,
+  # second, timezone, day of week].
+  #
+  # ParseDate.parsedate can also take a second argument, +comp+, which
+  # is a boolean telling the method to compensate for dates with years
+  # expressed as two digits. Example:
+  #
+  #   require 'parsedate'
+  #
+  #   ParseDate.parsedate "Mon Dec 25 00 06:53:24 UTC", true
+  #   # => [2000, 12, 25, 6, 53, 24, "UTC", 1]
+  #
   def parsedate(str, comp=false)
     Date._parse(str, comp).
       values_at(:year, :mon, :mday, :hour, :min, :sec, :zone, :wday)
diff --git a/lib/ping.rb b/lib/ping.rb
index 7728ece979..c2966b619c 100644
--- a/lib/ping.rb
+++ b/lib/ping.rb
@@ -1,35 +1,46 @@
 #
-# 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.
 #
 
 require 'timeout'
 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)
 #
 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")
     begin
       timeout(timeout) do