adding rdoc, unfinished

bdb.c

@@ -24,6 +24,14 @@ VALUE eDbError;
 
 static ID fv_call, fv_err_new,fv_err_code,fv_err_msg;
 
+/*
+ * Document-class: Bdb::DbError
+ *
+ * Errors generated by methods under the Bdb hierarchy will be
+ * of this class unless Ruby itself raises the error.
+ *
+ */
+
 static void
 #ifdef HAVE_STDARG_PROTOTYPES
 raise_error(int code, const char *fmt, ...)
@@ -50,6 +58,9 @@ raise_error(int code, const char *fmt, ...)
   rb_exc_raise(exc);
 }
 
+/*
+ * An error can only be generated internally
+ */
 VALUE err_initialize(VALUE obj, VALUE message, VALUE code)
 {
   VALUE args[1];
@@ -57,6 +68,12 @@ VALUE err_initialize(VALUE obj, VALUE message, VALUE code)
   rb_call_super(1,args);
   rb_ivar_set(obj,fv_err_code,code);
 }
+
+/*
+ * call-seq:
+ *   err.code() -> Bdb error code integer
+ *
+ */
 VALUE err_code(VALUE obj)
 {
   return rb_ivar_get(obj,fv_err_code);
@@ -153,11 +170,33 @@ VALUE db_init_aux(VALUE obj,t_envh * eh)
   return obj;
 }
 
+/*
+ * Document-class: Bdb::Db
+ *
+ */
+
 VALUE db_initialize(VALUE obj)
 {
   return db_init_aux(obj,NULL);
 }
 
+/*
+ * call-seq:
+ *	db.open(txn_object,disk_file,logical_db,db_type,flags,mode) -> value
+ *
+ * open a database. disk file is file path. logical_db is
+ * a named database within that file, which will be created under
+ * conditions noted by DB.
+ *
+ * db_type is one of the constants:
+ * Bdb::DB::BTREE
+ * Bdb::DB::HASH
+ * Bdb::DB::RECNO
+ * Bdb::DB::QUEUE
+ * Bdb::DB::UNKNOWN
+ *
+ * unknown will open an already existing db in the mode created
+ */
 VALUE db_open(VALUE obj, VALUE vtxn, VALUE vdisk_file,
 	      VALUE vlogical_db,
 	      VALUE vdbtype, VALUE vflags, VALUE vmode)
@@ -211,6 +250,14 @@ VALUE db_open(VALUE obj, VALUE vtxn, VALUE vdisk_file,
   return obj;
 }
 
+/*
+ * call-seq:
+ *	db.flags=value
+ *
+ * set database flags based on DB constants.
+ * see http://www.sleepycat.com/docs/api_c/db_set_flags.html
+ *
+ */
 VALUE db_flags_set(VALUE obj, VALUE vflags)
 {
   t_dbh *dbh;
@@ -228,6 +275,11 @@ VALUE db_flags_set(VALUE obj, VALUE vflags)
 
 VALUE dbc_close(VALUE);
 
+/* call-seq:
+ *	db.close(flags) -> value
+ *
+ * close a database handle. Will close open cursors.
+ */
 VALUE db_close(VALUE obj, VALUE vflags)
 {
   t_dbh *dbh;
@@ -265,6 +317,14 @@ VALUE db_close(VALUE obj, VALUE vflags)
   return obj;
 }
 
+/*
+ * call-seq:
+ *	db.put(txn,key,data,flags) -> self
+ *
+ * put a key/data pair into the database. returns db. Will
+ * raise an error on DB_KEYEXIST but error.code will indicate
+ * so it can be easily caught.
+ */
 VALUE db_put(VALUE obj, VALUE vtxn, VALUE vkey, VALUE vdata, VALUE vflags)
 {
   t_dbh *dbh;
@@ -305,6 +365,14 @@ VALUE db_put(VALUE obj, VALUE vtxn, VALUE vkey, VALUE vdata, VALUE vflags)
   return obj;
 }
 
+/*
+ * call-seq:
+ *	db.get(txn,key,data,flags) -> String(data)
+ *
+ * get a key/data pair from database. data as a string.
+ * 
+ */
+
 VALUE db_get(VALUE obj, VALUE vtxn, VALUE vkey, VALUE vdata, VALUE vflags)
 {
   t_dbh *dbh;
@@ -351,6 +419,14 @@ VALUE db_get(VALUE obj, VALUE vtxn, VALUE vkey, VALUE vdata, VALUE vflags)
   return Qnil;
 }
 
+/*
+ * call-seq:
+ *	db.pget(txn,key,data,flags) -> [pkey,data]
+ *
+ * get a key/data pair from database using a secondary index.
+ * returns an array with a primary key and the data element.
+ * 
+ */
 VALUE db_pget(VALUE obj, VALUE vtxn, VALUE vkey, VALUE vdata, VALUE vflags)
 {
   t_dbh *dbh;
@@ -402,14 +478,38 @@ VALUE db_pget(VALUE obj, VALUE vtxn, VALUE vkey, VALUE vdata, VALUE vflags)
   return Qnil;
 }
 
+/*
+ * call-seq:
+ *	db[key] -> data
+ *
+ * array ref style data retrieval
+ *
+ */
 VALUE db_aget(VALUE obj, VALUE vkey)
 {
   return db_get(obj,Qnil,vkey,Qnil,Qnil);
 }
+
+/*
+ * call-seq:
+ *	db[key]=data
+ *
+ * array ref style data storage
+ */
 VALUE db_aset(VALUE obj, VALUE vkey, VALUE vdata)
 {
   return db_put(obj,Qnil,vkey,vdata,Qnil);
 }
+
+/*
+ * call-seq:
+ *	db.join([cursors],flags) -> join_cursor
+ *
+ * create a join cursor from an array of cursors.
+ * The input cursors will usually be set_range and, if duplicate
+ * data items are allowed the should be DUP_SORT or the performance
+ * will be abysmal.
+ */
 VALUE db_join(VALUE obj, VALUE vacurs, VALUE vflags)
 {
   t_dbh *dbh;
@@ -440,6 +540,16 @@ VALUE db_join(VALUE obj, VALUE vacurs, VALUE vflags)
 }
 
 #if DB_VERSION_MINOR > 3
+/*
+ * call-seq:
+ *	db.compact(txn,start_key,stop_key,compact_opts,flags) -> end_key
+ *
+ * compact the database (4.4 an up). start and stop keys limit the
+ * range of compaction in BTREE types. compact_opts is currently
+ * ignored. Call returns the last key compacted (could be fed into
+ * a subsequent call as the start_key).
+ *
+ */
 VALUE db_compact(VALUE obj, VALUE vtxn, VALUE vstart_key,
 		 VALUE vstop_key, VALUE db_compact,
 		 VALUE vflags)
@@ -485,6 +595,14 @@ VALUE db_compact(VALUE obj, VALUE vtxn, VALUE vstart_key,
   
 }
 #endif
+
+/*
+ * call-seq:
+ * db.get_byteswapped -> true/false
+ *
+ * true if database is running in swapped mode. This happens when
+ * the db is created on a machine with a different endian.
+ */
 VALUE db_get_byteswapped(VALUE obj)
 {
   t_dbh *dbh;
@@ -495,9 +613,18 @@ VALUE db_get_byteswapped(VALUE obj)
   rv=dbh->db->get_byteswapped(dbh->db,&is_swapped);
   if (rv)
     raise_error(rv,"db_get_byteswapped failed: %s",db_strerror(rv));
-  return INT2FIX(is_swapped);
+  if (is_swapped)
+    return Qtrue;
+  else
+    return Qfalse;
 }
 
+/*
+ * call-seq:
+ * db.get_type -> Fixnum(type)
+ *
+ * an integer indicating the type of db (BTREE, HASH, etc).
+ */
 VALUE db_get_type(VALUE obj)
 {
   t_dbh *dbh;
@@ -511,6 +638,15 @@ VALUE db_get_type(VALUE obj)
   return INT2FIX(dbtype);
 }
 
+/*
+ * call-seq:
+ * db.remove(disk_file,logical_db,flags) -> true
+ *
+ * removes a whole database file, or just a logical_db within
+ * that file, i.e. if file and logical are both specified, only
+ * the logical will be removed. the Bdb::Db instance cannot have
+ * been previously used for anything and cannot be used after.
+ */
 VALUE db_remove(VALUE obj, VALUE vdisk_file,
 		VALUE vlogical_db, VALUE vflags)
 {
@@ -533,6 +669,12 @@ VALUE db_remove(VALUE obj, VALUE vdisk_file,
   return Qtrue;
 }
 
+/*
+ * call-seq:
+ * db.rename(file,logical,newname,flags) -> true
+ *
+ * rename a file or logical db to newname.
+ */
 VALUE db_rename(VALUE obj, VALUE vdisk_file,
 		VALUE vlogical_db, VALUE newname, VALUE vflags)
 {
@@ -560,6 +702,12 @@ VALUE db_rename(VALUE obj, VALUE vdisk_file,
   return Qtrue;
 }
 
+/*
+ * call-seq:
+ * db.sync -> true
+ *
+ * sync the database out to storage.
+ */
 VALUE db_sync(VALUE obj)
 {
   t_dbh *dbh;
@@ -573,6 +721,13 @@ VALUE db_sync(VALUE obj)
   return Qtrue;
 }
 
+/*
+ * call-seq:
+ * db.truncate(txn) -> Fixnum(record_count)
+ *
+ * truncate, i.e. remove all records, purge, trash.
+ *
+ */
 VALUE db_truncate(VALUE obj, VALUE vtxn)
 {
   t_dbh *dbh;
@@ -593,6 +748,14 @@ VALUE db_truncate(VALUE obj, VALUE vtxn)
   return INT2FIX(count);
 }
 
+/*
+ * call-seq:
+ * db.key_range(txn,vkey,flags) -> [#less,#same,#greater]
+ *
+ * calculate position of key within database. returns the counts
+ * of keys less, same and greater than the given key as an
+ * array of Fixnum-s
+ */
 VALUE db_key_range(VALUE obj, VALUE vtxn, VALUE vkey, VALUE vflags)
 {
   t_dbh *dbh;
@@ -629,6 +792,15 @@ VALUE db_key_range(VALUE obj, VALUE vtxn, VALUE vkey, VALUE vflags)
   return result;
 }
 
+/*
+ * call-seq:
+ * db.del(txn,key,flags) -> true/nil
+ *
+ * delete records with the key given. DUP values will removed
+ * as a group. true if deleted extant records. NIL if the
+ * operation resulted in DB indicating DB_NOTFOUND.
+ *
+ */
 VALUE db_del(VALUE obj, VALUE vtxn, VALUE vkey, VALUE vflags)
 {
   t_dbh *dbh;
@@ -700,6 +872,24 @@ int assoc_callback(DB *secdb,const DBT* key, const DBT* data, DBT* result)
   return 0;
 }
 
+/*
+ * call-seq:
+ * db.associate(txn,sec_db,flags,proc)
+ *
+ * associate a secondary index(database) with this (primary)
+ * database. The proc can be nil if the database is only opened
+ * DB_RDONLY. Only +one+ proc can be assigned to a given database
+ * according to the file-descriptor number of the secondary within
+ * a single ruby process. This is typcially not an issue since
+ * the proc should always be the same (it would corrupt the
+ * secondary otherwise). But this does limit use of nil if the
+ * db is openend DB_RDONLY and writeable in the same process.
+ * (although, opening the same db more than once has not been
+ * tested)
+ *
+ * call back proc has signature:
+ * proc(secdb,key,value)
+ */
 VALUE db_associate(VALUE obj, VALUE vtxn, VALUE osecdb,
 		   VALUE vflags, VALUE cb_proc)
 {
@@ -751,6 +941,12 @@ VALUE db_associate(VALUE obj, VALUE vtxn, VALUE osecdb,
   return Qtrue;
 }
 
+/*
+ * call-seq:
+ * db.cursor(txn,flags)
+ *
+ * open a cursor
+ */
 VALUE db_cursor(VALUE obj, VALUE vtxn, VALUE vflags)
 {
   t_dbh *dbh;
@@ -780,6 +976,12 @@ VALUE db_cursor(VALUE obj, VALUE vtxn, VALUE vflags)
   return c_obj;
 }
 
+/*
+ * call-seq:
+ * dbc.close -> nil
+ *
+ * close an open cursor
+ */
 VALUE dbc_close(VALUE obj)
 {
   t_dbch *dbch;
@@ -1559,6 +1761,7 @@ VALUE txn_set_timeout(VALUE obj, VALUE vtimeout, VALUE vflags)
   return Qtrue;
 }
 
+
 void Init_bdb2() {
   fv_call=rb_intern("call");
   fv_err_new=rb_intern("new");
@@ -1585,7 +1788,7 @@ void Init_bdb2() {
 
   rb_define_method(cDb,"put",db_put,4);
   rb_define_method(cDb,"get",db_get,4);
-  rb_define_method(cDb,"pget",db_get,4);
+  rb_define_method(cDb,"pget",db_pget,4);
   rb_define_method(cDb,"del",db_del,3);
   rb_define_method(cDb,"cursor",db_cursor,2);
   rb_define_method(cDb,"associate",db_associate,4);