From 934f5dff37764a2419b35ae6c7cf5e7e89bb9e83 Mon Sep 17 00:00:00 2001
From: Zachary Scott <zachary@zacharyscott.net>
Date: Thu, 10 May 2012 11:29:27 -0400
Subject: [PATCH] clean documentation for SDBM patch

---
 ext/sdbm/init.c |  103 +++++++++++++++++++++++++++----------------------------
 1 files changed, 51 insertions(+), 52 deletions(-)

diff --git a/ext/sdbm/init.c b/ext/sdbm/init.c
index a974053..f94a933 100644
--- a/ext/sdbm/init.c
+++ b/ext/sdbm/init.c
@@ -121,7 +121,7 @@ fsdbm_close(VALUE obj)
 * call-seq:
 *     sdbm.closed? -> true or false
 *
-* Returns true if the database is closed.
+* Returns +true+ if the database is closed.
 */
 static VALUE
 fsdbm_closed(VALUE obj)
@@ -146,13 +146,16 @@ fsdbm_alloc(VALUE klass)
 * call-seq:
 *      SDBM.new(filename, mode = 0666)
 *
-* Creates a new database handle by opening the given _filename_. sdbm actually
+* Creates a new database handle by opening the given _filename_. SDBM actually
 * uses two physical files, with extensions '.dir' and '.pag'. These extensions
 * will automatically be appended to the _filename_.
 *
-* If the file does not exist, a new file will be created using the given _mode_, unless _mode_ is explicitly set to nil. In the latter case, no database will be created.
+* If the file does not exist, a new file will be created using the given
+* _mode_, unless _mode_ is explicitly set to nil. In the latter case, no
+* database will be created.
 *
-* If the file exists, it will be opened in read/write mode. If this fails, it will be opened in read-only mode.
+* If the file exists, it will be opened in read/write mode. If this fails, it
+* will be opened in read-only mode.
 */
 static VALUE
 fsdbm_initialize(int argc, VALUE *argv, VALUE obj)
@@ -200,10 +203,10 @@ fsdbm_initialize(int argc, VALUE *argv, VALUE obj)
  *      SDBM.open(filename, mode = 0666)
  *      SDBM.open(filename, mode = 0666) { |sdbm| ... }
  *
- * If called without a block, this is the same as SDBM.new.
+ * If called without a _block_, this is the same as SDBM.new.
  *
- * If a block is given, the new database will be passed to the block and
- * will be safely closed after the block has executed.
+ * If a _block_ is given, the new database will be passed to the _block_ and
+ * will be safely closed after the _block_ has executed.
  *
  * Example:
  *
@@ -254,9 +257,9 @@ fsdbm_fetch(VALUE obj, VALUE keystr, VALUE ifnone)
  * call-seq:
  *      sdbm[key] -> value or nil
  *
- * Returns the value in the database associated with the given _key_ string.
+ * Returns the _value_ in the database associated with the given _key_ string.
  *
- * If no value is found, returns nil.
+ * If no value is found, returns +nil+.
  */
 static VALUE
 fsdbm_aref(VALUE obj, VALUE keystr)
@@ -269,13 +272,13 @@ fsdbm_aref(VALUE obj, VALUE keystr)
  *      sdbm.fetch(key) -> value or nil
  *      sdbm.fetch(key) { |key| ... }
  *
- * Returns the value in the database associated with the given _key_ string.
+ * Returns the _value_ in the database associated with the given _key_ string.
  *
- * If a block is provided, the block will be called when there is no value
+ * If a _block_ is provided, the _block_ will be called when there is no _value_
  * associated with the given _key_. The _key_ will be passed in as an argument to
- * the block.
+ * the _block_.
  *
- * If no block is provided and no value is associated with the given  _key_,
+ * If no _block_ is provided and no value is associated with the given _key_,
  * then an IndexError will be raised.
  */
 static VALUE
@@ -295,9 +298,9 @@ fsdbm_fetch_m(int argc, VALUE *argv, VALUE obj)
  * call-seq:
  *      sdbm.key(value) -> key
  *
- * Returns the key associated with the given _value_. If more than one
- * key corresponds to the given value, then the first key to be found
- * will be returned. If no keys are found, nil will be returned.
+ * Returns the _key_ associated with the given _value_. If more than one
+ * _key_ corresponds to the given _value_, then the first key to be found
+ * will be returned. If no keys are found, +nil+ will be returned.
  */
 static VALUE
 fsdbm_key(VALUE obj, VALUE valstr)
@@ -321,10 +324,7 @@ fsdbm_key(VALUE obj, VALUE valstr)
 }
 
 /*
- * call-seq:
- *      sdbm.index(value) -> key
- *
- * This method is the same as SDBM#key and has been deprecated.
+ * :nodoc:
  */
 static VALUE
 fsdbm_index(VALUE hash, VALUE value)
@@ -334,10 +334,9 @@ fsdbm_index(VALUE hash, VALUE value)
 }
 
 /* call-seq:
- *      sdbm.select { |key, value| block } -> array
+ *      sdbm.select { |key, value| block } -> Array
  *
- * Returns a new array of key-value pairs for which the _block_ returns
- * true.
+ * Returns a new Array of key-value pairs for which the _block_ returns +true+.
  *
  * Example:
  *
@@ -350,7 +349,7 @@ fsdbm_index(VALUE hash, VALUE value)
  *
  *      veggies = db.select do |key, value|
  *        value == 'vegetable'
- *      end                    #=> [["apple", "fruit"], ["pear", "fruit"]]
+ *      end #=> [["apple", "fruit"], ["pear", "fruit"]]
  *    end
  */
 static VALUE
@@ -378,9 +377,9 @@ fsdbm_select(VALUE obj)
 }
 
 /* call-seq:
- *      sdbm.values_at(key, ...) -> array
+ *      sdbm.values_at(key, ...) -> Array
  *
- * Returns an array of values corresponding to the given keys.
+ * Returns an Array of values corresponding to the given keys.
  */
 static VALUE
 fsdbm_values_at(int argc, VALUE *argv, VALUE obj)
@@ -407,12 +406,12 @@ fdbm_modify(VALUE obj)
  *      sdbm.delete(key) -> value or nil
  *      sdbm.delete(key) { |key, value| ... }
  *
- * Deletes the kay-value pair corresponding to the given _key_. If the
- * key exists, the deleted value will be returned, otherwise nil.
+ * Deletes the key-value pair corresponding to the given _key_. If the
+ * _key_ exists, the deleted value will be returned, otherwise +nil+.
  *
- * If a block is provided, the deleted key and value will be passed to the
- * block as arguments. If the key does not exist in the database, the
- * value will be nil.
+ * If a _block_ is provided, the deleted _key_ and _value_ will be passed to
+ * the _block_ as arguments. If the _key_ does not exist in the database, the
+ * value will be +nil+.
  */
 static VALUE
 fsdbm_delete(VALUE obj, VALUE keystr)
@@ -451,10 +450,10 @@ fsdbm_delete(VALUE obj, VALUE keystr)
 
 /*
  * call-seq:
- *      sdbm.shift -> array or nil
+ *      sdbm.shift -> Array or nil
  *
  * Removes a key-value pair from the database and returns them as an
- * array. If the database is empty, returns nil.
+ * Array. If the database is empty, returns +nil+.
  */
 static VALUE
 fsdbm_shift(VALUE obj)
@@ -485,7 +484,7 @@ fsdbm_shift(VALUE obj)
  *      sdbm.reject! { |key, value| block } -> self
  *
  * Iterates over the key-value pairs in the database, deleting those for
- * which the _block_ returns true.
+ * which the _block_ returns +true+.
  */
 static VALUE
 fsdbm_delete_if(VALUE obj)
@@ -591,10 +590,10 @@ fsdbm_invert(VALUE obj)
  * call-seq:
  *      sdbm.store(key, value) -> value
  *
- * Stores a new value in the database with the given _key_ as an index.
+ * Stores a new _value_ in the database with the given _key_ as an index.
  *
- * If the key already exists, this will update the value associated with
- * the key.
+ * If the _key_ already exists, this will update the _value_ associated with
+ * the _key_.
  *
  * Returns the given _value_.
  */
@@ -707,7 +706,7 @@ fsdbm_length(VALUE obj)
  * call-seq:
  *      sdbm.empty? -> true or false
  *
- * Returns true if the database is empty.
+ * Returns +true+ if the database is empty.
  */
 static VALUE
 fsdbm_empty_p(VALUE obj)
@@ -737,9 +736,9 @@ fsdbm_empty_p(VALUE obj)
  *      sdbm.each_value
  *      sdbm.each_value { |value| ... }
  *
- * Iterates over each value in the database.
+ * Iterates over each _value_ in the database.
  *
- * If no block is given, returns an Enumerator.
+ * If no _block_ is given, returns an Enumerator.
  */
 static VALUE
 fsdbm_each_value(VALUE obj)
@@ -764,9 +763,9 @@ fsdbm_each_value(VALUE obj)
  *      sdbm.each_key
  *      sdbm.each_key { |key| ... }
  *
- * Iterates over each key in the database.
+ * Iterates over each _key_ in the database.
  *
- * If no block is given, returns an Enumerator.
+ * If no _block_ is given, returns an Enumerator.
  */
 static VALUE
 fsdbm_each_key(VALUE obj)
@@ -792,7 +791,7 @@ fsdbm_each_key(VALUE obj)
  *
  * Iterates over each key-value pair in the database.
  *
- * If no block is given, returns an Enumerator.
+ * If no _block_ is given, returns an Enumerator.
  */
 static VALUE
 fsdbm_each_pair(VALUE obj)
@@ -818,9 +817,9 @@ fsdbm_each_pair(VALUE obj)
 
 /*
  * call-seq:
- *      sdbm.keys -> array
+ *      sdbm.keys -> Array
  *
- * Returns a new array containing the keys in the database.
+ * Returns a new Array containing the keys in the database.
  */
 static VALUE
 fsdbm_keys(VALUE obj)
@@ -841,9 +840,9 @@ fsdbm_keys(VALUE obj)
 
 /*
  * call-seq:
- *      sdbm.values -> array
+ *      sdbm.values -> Array
  *
- * Returns a new array containing the values in the database.
+ * Returns a new Array containing the values in the database.
  */
 static VALUE
 fsdbm_values(VALUE obj)
@@ -867,7 +866,7 @@ fsdbm_values(VALUE obj)
  * call-seq:
  *      sdbm.has_key?(key) -> true or false
  *
- * Returns true if the database contains the given _key_.
+ * Returns +true+ if the database contains the given _key_.
  */
 static VALUE
 fsdbm_has_key(VALUE obj, VALUE keystr)
@@ -890,7 +889,7 @@ fsdbm_has_key(VALUE obj, VALUE keystr)
  * call-seq:
  *      sdbm.has_value?(key) -> true or false
  *
- * Returns true if the database contains the given _value_.
+ * Returns +true+ if the database contains the given _value_.
  */
 static VALUE
 fsdbm_has_value(VALUE obj, VALUE valstr)
@@ -915,9 +914,9 @@ fsdbm_has_value(VALUE obj, VALUE valstr)
 
 /*
  * call-seq:
- *      sdbm.to_a -> array
+ *      sdbm.to_a -> Array
  *
- * Returns a new array containing each key-value pair in the database.
+ * Returns a new Array containing each key-value pair in the database.
  *
  * Example:
  *
@@ -979,7 +978,7 @@ fsdbm_to_hash(VALUE obj)
  *
  * Creates a new Hash using the key-value pairs from the database, then
  * calls Hash#reject with the given _block_, which returns a Hash with
- * only the key-value pairs for which the block returns false.
+ * only the key-value pairs for which the _block_ returns +false+.
  */
 static VALUE
 fsdbm_reject(VALUE obj)
-- 
1.7.4.1

