* 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

1 files changed, 30 insertions, 19 deletions

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