RDoc abbrev

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

1 files changed, 38 insertions, 0 deletions

diff --git a/lib/abbrev.rb b/lib/abbrev.rb
index 9cd3a71e40..6530679681 100644
--- a/lib/abbrev.rb
+++ b/lib/abbrev.rb
@@ -1,4 +1,5 @@
 #!/usr/bin/env ruby
+=begin
 #
 # Copyright (c) 2001,2003 Akinori MUSHA <knu@iDaemons.org>
 #
@@ -8,8 +9,38 @@
 # $Idaemons: /home/cvs/rb/abbrev.rb,v 1.2 2001/05/30 09:37:45 knu Exp $
 # $RoughId: abbrev.rb,v 1.4 2003/10/14 19:45:42 knu Exp $
 # $Id$
+=end
+
+# Calculate the set of unique abbreviations for a given set of strings.
+#
+#   require 'abbrev'
+#   require 'pp'
+#
+#   pp Abbrev::abbrev(['ruby', 'rules']).sort
+#
+# <i>Generates:</i>
+#
+#   [["rub", "ruby"],
+#    ["ruby", "ruby"],
+#    ["rul", "rules"],
+#    ["rule", "rules"],
+#    ["rules", "rules"]]
+#
+# Also adds an +abbrev+ method to class +Array+.
 
 module Abbrev
+
+  # Given a set of strings, calculate the set of unambiguous
+  # abbreviations for those strings, and return a hash where the keys
+  # are all the possible abbreviations and the values are the full
+  # strings. Thus, given input of "car" and "cone", the keys pointing
+  # to "car" would be "ca" and "car", while those pointing to "cone"
+  # would be "co", "con", and "cone".
+  #
+  # The optional +pattern+ parameter is a pattern or a string. Only
+  # those input strings matching the pattern, or begging the string,
+  # are considered for inclusion in the output hash
+
   def abbrev(words, pattern = nil)
     table = {}
     seen = Hash.new(0)
@@ -49,6 +80,13 @@ module Abbrev
 end
 
 class Array
+  # Calculates the set of unambiguous abbreviations for the strings in
+  # +self+. If passed a pattern or a string, only the strings matching
+  # the pattern or starting with the string are considered.
+  #
+  #   %w{ car cone }.abbrev   #=> { "ca" => "car", "car" => "car",
+  #                                 "co" => "cone", "con" => cone",
+  #                                 "cone" => "cone" }
   def abbrev(pattern = nil)
     Abbrev::abbrev(self, pattern)
   end