fix doxygen warnings

stasis/compensations.h

@@ -3,9 +3,15 @@
 #ifndef __COMPENSATIONS_H
 #define __COMPENSATIONS_H
 
-BEGIN_C_DECLS
+/**
+  @file
 
-/** Rants about cpp:
+  An incomplete implementation of compensations for C (deprecated)
+
+  @deprecated Don't use compensations in new code.  For now, abort()
+  the process on error.
+
+  Rants about cpp:
 
   There seems to be no way to add this syntax:
   
@@ -49,7 +55,7 @@ void lock_c_line_1231(lock * l) {
   enclosing function's scope, since nested functions cannot be called
   after the function they are declared in returns.
 
-  You could try #defining a temporary variable, and reading from it in
+  You could try \#defining a temporary variable, and reading from it in
   the 'with' macro, but you seem to need a stack in order to support
   that.
 
@@ -93,14 +99,17 @@ void lock_c_line_1231(lock * l) {
   function will not work.  This could probably be partially fixed by
   replacing return statements with 'break' statements, or a GOTO to
   the proper enclosing end_action/compensate.  There may be a way to
-  #define/#undefine a variable in a way that would handle this
+  \#define/\#undefine a variable in a way that would handle this
   properly.
 
   Also, begin_action(NULL, NULL) is supported, and is useful for
   checking the return value of a called function, but, for
   efficiency, try{ } end; is recommended
+
 */
 
+BEGIN_C_DECLS
+
 void compensations_init();
 void compensations_deinit();
 long compensation_error();

stasis/operations/linearHashNTA.h

@@ -67,10 +67,9 @@ lladd_hash_iterator * ThashIterator(int xid, recordid hash, int keySize, int val
   Obtain the next value in the hash table.  
   
   @return 1 if another value exists; 0 if the iterator is done, and has been deallocated.
-  @param keySize Currently, keySize and valueSize must
-  be set to the correct sizes when ThashNext is called.  Once hashtables with 
-  variable sized entries are supported, this restriction will be relaxed or removed
-  entirely.
+
+  @param xid Transaction id
+  @param it The iterator that will be traversed.  @see ThashIterator().
   @param key a pointer to an uninitialized pointer value.  If another entry is 
          encountered, then the uninitialized pointer value will be set to point 
          to a malloc()'ed region of memory that contains the value's key.  This 
@@ -80,10 +79,12 @@ lladd_hash_iterator * ThashIterator(int xid, recordid hash, int keySize, int val
          difficult for the application to malloc an appropriate buffer for the 
 	 iterator, so this function call does not obey normal LLADD calling 
 	 semantics.
+  @param keySize The address of a valid integer.  It's initial value is ignored, 
+         and will be overwritten by the length of the key.
   @param value analagous to value.
   @param valueSize analagous to keySize
 
-  @deprecated  @see interator.h.  Use the linearHash implementation of that interface instead.
+  @deprecated  Use iterator.h's linearHash implementation instead.
 */
 int ThashNext(int xid, lladd_hash_iterator * it, byte ** key, int * keySize, byte** value, int * valueSize);
 

stasis/transactional.h

@@ -605,14 +605,26 @@ int Tbegin();
  * @param xid          The current transaction.
  * @param rid          The record the operation pertains to.  For some logical operations, this will be a dummy record.
  * @param dat          Application specific data to be recorded in the log (for undo/redo), and to be passed to the implementation of op.
+ * @param datlen       The length of dat, in bytes.
  * @param op           The operation's offset in operationsTable
  *
  * @see operations.h set.h
  */
 compensated_function void Tupdate(int xid, recordid rid, 
 				  const void *dat, size_t datlen, int op);
+/**
+   @deprecated Only exists to work around swig/python limitations.
+ */
 compensated_function void TupdateStr(int xid, recordid rid, 
                                      const char *dat, size_t datlen, int op);
+/**
+   Like Tupdate(), but does not call stasis_record_dereference().
+   Tupdate() no longe calls stasis_record_dereference(), but has some
+   sanity checks that will make TupdateRaw() necessary until I'm sure
+   that no remaining code relies on the old behavior.
+
+   @deprecated If you need to call this function, be prepared to change your code.
+ */
 compensated_function void TupdateRaw(int xid, recordid rid, 
 				     const void *dat, size_t datlen, int op);
 /**
@@ -688,8 +700,6 @@ void Trevive(int xid, lsn_t prevlsn, lsn_t reclsn);
     @todo move prepare to prepare.[ch]
 
     @param xid Transaction id.
-    @param rec must be a valid record id.  any valid recordid will do.  This parameter will be removed eventually.
-
 */
 int Tprepare(int xid);
 /**