From cd3d6d573985cac087bd51f44bd8ad87b9e4e429 Mon Sep 17 00:00:00 2001
From: Eric Wong <normalperson@yhbt.net>
Date: Thu, 2 Dec 2010 14:14:12 -0800
Subject: RDoc updates

We still need a lot of work in this area, but this is better
than nothing.
---
 ext/tdb/tdb.c | 65 +++++++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 48 insertions(+), 17 deletions(-)

(limited to 'ext')

diff --git a/ext/tdb/tdb.c b/ext/tdb/tdb.c
index 0ad7d5f..a68c360 100644
--- a/ext/tdb/tdb.c
+++ b/ext/tdb/tdb.c
@@ -205,6 +205,34 @@ static void set_args(struct open_args *o, VALUE opts)
 	}
 }
 
+/*
+ * :call-seq:
+ *
+ *	TDB.new("/path/to/file") -> TDB
+ *	TDB.new("/path/to/file", :hash_size => 666) -> TDB
+ *	TDB.new("/path/to/file", :hash => :murmur2) -> TDB
+ *	TDB.new("/path/to/file", :open_flags => IO::RDONLY) -> TDB
+ *	TDB.new("/path/to/file", :tdb_flags => TDB::NOSYNC) -> TDB
+ *
+ * Initializes a TDB context.  It takes several options.
+ *
+ * :hash_size - the number of buckets, this is the most important tuning
+ * parameter when creating large databases.  This parameter only affects
+ * the creation of new databases.
+ *
+ * :open_flags - a bit mask of IO flags passed directly to open(2),
+ * File.open-compatible flags are accepted.
+ *
+ * :hash - any of the hashes described in Hash_Functions.
+ * This must remain the same for all clients.
+ *
+ * :tdb_flags - a bitmask of any combination of TDB::CLEAR_IF_FIRST,
+ * TDB::INTERNAL, TDB::NOLOCK, TDB::NOMMAP, TDB::CONVERT,
+ * TDB::BIGENDIAN, TDB::NOSYNC, TDB::SEQNUM, TDB::VOLATILE,
+ * TDB::ALLOW_NESTING, TDB::DISALLOW_NESTING, TDB::INCOMPATIBLE_HASH
+ *
+ * :mode - octal mode mask passed to open(2)
+ */
 static VALUE init(int argc, VALUE *argv, VALUE self)
 {
 	struct tdb_context *tdb = db(self, 0);
@@ -592,7 +620,12 @@ void Init_tdb_ext(void)
 	cTDB = rb_define_class("TDB", rb_cObject);
 
 	hashes = rb_hash_new();
-        rb_define_const(cTDB, "HASHES", hashes);
+
+	/*
+	 * Available hash functions, the key is the name of the hash
+	 * and the value is a pointer for internal for usage.
+	 */
+	rb_define_const(cTDB, "HASHES", hashes);
 
 	rb_define_alloc_func(cTDB, alloc);
 	rb_include_module(cTDB, rb_mEnumerable);
@@ -630,51 +663,49 @@ void Init_tdb_ext(void)
 	init_errors();
 	init_hashes();
 
-#define tdb_CONST(x) rb_define_const(cTDB, #x, UINT2NUM(TDB_##x))
-
 	/* just a readability place holder */
-	tdb_CONST(DEFAULT);
+	rb_define_const(cTDB, "DEFAULT", UINT2NUM(TDB_DEFAULT));
 
 	/* clear database if we are the only one with it open */
-	tdb_CONST(CLEAR_IF_FIRST);
+	rb_define_const(cTDB, "CLEAR_IF_FIRST", UINT2NUM(TDB_CLEAR_IF_FIRST));
 
 	/* don't store on disk, use in-memory database */
-	tdb_CONST(INTERNAL);
+	rb_define_const(cTDB, "INTERNAL", UINT2NUM(TDB_INTERNAL));
 
 	/* don't do any locking */
-	tdb_CONST(NOLOCK);
+	rb_define_const(cTDB, "NOLOCK", UINT2NUM(TDB_NOLOCK));
 
 	/* don't use mmap */
-	tdb_CONST(NOMMAP);
+	rb_define_const(cTDB, "NOMMAP", UINT2NUM(TDB_NOMMAP));
 
 	/* convert endian (internal use) */
-	tdb_CONST(CONVERT);
+	rb_define_const(cTDB, "CONVERT", UINT2NUM(TDB_CONVERT));
 
 	/* header is big-endian (internal use) */
-	tdb_CONST(BIGENDIAN);
+	rb_define_const(cTDB, "BIGENDIAN", UINT2NUM(TDB_BIGENDIAN));
 
 	/* don't use synchronous transactions */
-	tdb_CONST(NOSYNC);
+	rb_define_const(cTDB, "NOSYNC", UINT2NUM(TDB_NOSYNC));
 
 	/* maintain a sequence number */
-	tdb_CONST(SEQNUM);
+	rb_define_const(cTDB, "SEQNUM", UINT2NUM(TDB_SEQNUM));
 
 	/* Activate the per-hashchain freelist, default 5 */
-	tdb_CONST(VOLATILE);
+	rb_define_const(cTDB, "VOLATILE", UINT2NUM(TDB_VOLATILE));
 
 #ifdef TDB_ALLOW_NESTING
 	/* Allow transactions to nest */
-	tdb_CONST(ALLOW_NESTING);
+	rb_define_const(cTDB, "ALLOW_NESTING", UINT2NUM(TDB_ALLOW_NESTING));
 #endif
 
 #ifdef TDB_DISALLOW_NESTING
 	/* Disallow transactions to nest */
-	tdb_CONST(DISALLOW_NESTING);
+	rb_define_const(cTDB, "DISALLOW_NESTING", UINT2NUM(TDB_DISALLOW_NESTING));
 #endif
 
 #ifdef TDB_INCOMPATIBLE_HASH
-	/* Better hashing: can't be opened by tdb < 1.2.6. */
-	tdb_CONST(INCOMPATIBLE_HASH);
+	/* Better hashing, but can't be opened by tdb < 1.2.6. */
+	rb_define_const(cTDB, "INCOMPATIBLE_HASH", UINT2NUM(TDB_INCOMPATIBLE_HASH));
 #endif
 }
 
-- 
cgit v1.2.3-24-ge0c7