1 files changed, 43 insertions, 10 deletions
diff --git a/lib/find.rb b/lib/find.rb
index 3c16533794..9ca39cabcb 100644
--- a/lib/find.rb
+++ b/lib/find.rb
@@ -1,16 +1,40 @@
-# Usage:
-#	require "find"
 #
-#	Find.find('/foo','/bar') {|f| ...}
-#  or
-#	include Find
-#	find('/foo','/bar') {|f| ...}
+# find.rb: the Find module for processing all files under a given directory.
 #
 
+#
+# The +Find+ module supports the top-down traversal of a set of file paths.
+#
+# For example, to total the size of all files under your home directory,
+# ignoring anything in a "dot" directory (e.g. $HOME/.ssh):
+#
+#   require 'find'
+#
+#   total_size = 0
+#
+#   Find.find(ENV["HOME"]) do |path|
+#     if FileTest.directory?(path)
+#       if File.basename(path)[0] == ?.
+#         Find.prune       # Don't look any further into this directory.
+#       else
+#         next
+#       end
+#     else
+#       total_size += FileTest.size(path)
+#     end
+#   end
+#
 module Find
-  def find(*path)
-    path.collect!{|d| d.dup}
-    while file = path.shift
+
+  #
+  # Calls the associated block with the name of every file and directory listed
+  # as arguments, then recursively on their subdirectories, and so on.
+  #
+  # See the +Find+ module documentation for an example.
+  #
+  def find(*paths) # :yield: path
+    paths.collect!{|d| d.dup}
+    while file = paths.shift
       catch(:prune) do
 	yield file
 	begin
@@ -26,7 +50,7 @@ module Find
 		else
 		  f = File.join(file, f)
 		end
-		path.unshift f
+		paths.unshift f
 	      end
 	    ensure
 	      d.close
@@ -38,8 +62,17 @@ module Find
     end
   end
 
+  #
+  # Skips the current file or directory, restarting the loop with the next
+  # entry. If the current file is a directory, that directory will not be
+  # recursively entered. Meaningful only within the block associated with
+  # Find::find.
+  #
+  # See the +Find+ module documentation for an example.
+  #
   def prune
     throw :prune
   end
+
   module_function :find, :prune
 end