From 8e40b0ee910634b06ea1e47f50ff7b5d66a42a0a Mon Sep 17 00:00:00 2001
From: Mani Tadayon <bowsersenior@gmail.com>
Date: Mon, 16 May 2011 20:55:14 -0700
Subject: [PATCH] Add documentation for YAML::DBM

---
 lib/yaml/dbm.rb |   63 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 62 insertions(+), 1 deletions(-)

diff --git a/lib/yaml/dbm.rb b/lib/yaml/dbm.rb
index 973e88d..717c629 100644
--- a/lib/yaml/dbm.rb
+++ b/lib/yaml/dbm.rb
@@ -6,14 +6,26 @@ require 'dbm'
 #
 module YAML
 
+# Inherit from ::DBM class (see /ext/dbm/dbm.c)
 class DBM < ::DBM
+    # YAML::DBM Version
     VERSION = "0.1"
+
+    # Return a value from the database by locating the key string
+    # provided.  If the key is not found, returns nil.
     def []( key )
         fetch( key )
     end
+
+    # Stores the specified string value in the database, indexed via the
+    # string key provided.
     def []=( key, val )
         store( key, val )
     end
+
+    # Return a value from the database by locating the key string
+    # provided.  If the key is not found, returns +ifnone+. If +ifnone+
+    # is not given, raises IndexError.
     def fetch( keystr, ifnone = nil )
         begin
             val = super( keystr )
@@ -26,12 +38,17 @@ class DBM < ::DBM
             ifnone
         end
     end
-    def index( keystr )
+
+    def index( keystr ) # :nodoc:
         super( keystr.to_yaml )
     end
+
+    # Returns an array containing the values associated with the given keys.
     def values_at( *keys )
         keys.collect { |k| fetch( k ) }
     end
+
+    # Deletes an entry from the database.
     def delete( key )
         v = super( key )
         if String === v
@@ -39,45 +56,75 @@ class DBM < ::DBM
         end
         v
     end
+
+    # Deletes all entries for which the code block returns true.
+    # Returns self.
     def delete_if
         del_keys = keys.dup
         del_keys.delete_if { |k| yield( k, fetch( k ) ) == false }
         del_keys.each { |k| delete( k ) }
         self
     end
+
+    # Converts the contents of the database to an in-memory Hash, then calls
+    # Hash#reject with the specified code block, returning a new Hash.
     def reject
         hsh = self.to_hash
         hsh.reject { |k,v| yield k, v }
     end
+
+    # Calls the block once for each [key, value] pair in the database.
+    # Returns self.
     def each_pair
         keys.each { |k| yield k, fetch( k ) }
         self
     end
+
+    # Calls the block once for each value string in the database. Returns self.
     def each_value
         super { |v| yield YAML.load( v ) }
         self
     end
+
+    # Returns an array containing the values associated with the given keys.
     def values
         super.collect { |v| YAML.load( v ) }
     end
+
+    # Returns true if the database contains the specified string value, false
+    # otherwise.
     def has_value?( val )
         each_value { |v| return true if v == val }
         return false
     end
+
+    # Returns a Hash (not a DBM database) created by using each value in the
+    # database as a key, with the corresponding key as its value.
     def invert
         h = {}
         keys.each { |k| h[ self.fetch( k ) ] = k }
         h
     end
+
+    # Replaces the contents of the database with the contents of the specified
+    # object. Takes any object which implements the each_pair method, including
+    # Hash and DBM objects.
     def replace( hsh )
         clear
         update( hsh )
     end
+
+    # Removes a [key, value] pair from the database, and returns it.
+    # If the database is empty, returns nil.
+    # The order in which values are removed/returned is not guaranteed.
     def shift
         a = super
         a[1] = YAML.load( a[1] ) if a
         a
     end
+
+    # Returns a new array consisting of the [key, value] pairs for which the code
+    # block returns true.
     def select( *keys )
         if block_given?
             self.keys.collect { |k| v = self[k]; [k, v] if yield k, v }.compact
@@ -85,26 +132,40 @@ class DBM < ::DBM
             values_at( *keys )
         end
     end
+
+    # Stores the specified string value in the database, indexed via the
+    # string key provided.
     def store( key, val )
         super( key, val.to_yaml )
         val
     end
+
+    # Updates the database with multiple values from the specified object.
+    # Takes any object which implements the each_pair method, including
+    # Hash and DBM objects.
     def update( hsh )
         hsh.keys.each do |k|
             self.store( k, hsh.fetch( k ) )
         end
         self
     end
+
+    # Converts the contents of the database to an array of [key, value] arrays,
+    # and returns it.
     def to_a
         a = []
         keys.each { |k| a.push [ k, self.fetch( k ) ] }
         a
     end
+
+    # Converts the contents of the database to an in-memory Hash object, and
+    # returns it.
     def to_hash
         h = {}
         keys.each { |k| h[ k ] = self.fetch( k ) }
         h
     end
+
     alias :each :each_pair
 end
 
-- 
1.7.4.1