[libimdb-commit] CVS: libimdb/libjlog jlog.c,1.2,1.3 jlog2File.c,1.2,1.3 jlogTracker.c,1.1,1.2

[Jerry V. <jve...@us...>]

Update of /cvsroot/libimdb/libimdb/libjlog
In directory sc8-pr-cvs1:/tmp/cvs-serv20497/libjlog

Modified Files:
	jlog.c jlog2File.c jlogTracker.c 
Log Message:
a flurry of documentation done

Index: jlog.c
===================================================================
RCS file: /cvsroot/libimdb/libimdb/libjlog/jlog.c,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** jlog.c	21 Aug 2003 22:45:18 -0000	1.2
--- jlog.c	28 Aug 2003 15:25:00 -0000	1.3
***************
*** 24,29 ****
  #include "jlog/jlogTracker.h"
  
! typedef struct mymod_s { jlogModule_e mod; char *str; } mymod_t;
  
  jlogCallbackHandle_t *
  jlogCallback_create(jlog_eventCallback_t *cb,
--- 24,41 ----
  #include "jlog/jlogTracker.h"
  
! /**
!  * private management struct of mod to string translation
!  */
! typedef struct mymod_s {
!     jlogModule_e mod;		/**< module */
!     char *str;			/**< equivalent string representation */
! } mymod_t;
  
+ /**
+  * allocate and initialize a new jlogCallbackHandle_t
+  *
+  * @returns NULL on malloc failure
+  * @returns jlogCallbackHandle_t handle upon success
+  */
  jlogCallbackHandle_t *
  jlogCallback_create(jlog_eventCallback_t *cb,
***************
*** 46,50 ****
  }
  
! 
  void
  jlogCallback_destroy(jlogCallbackHandle_t *l)
--- 58,64 ----
  }
  
! /**
!  * deallocate a jlogCallbackHandle_t
!  */
  void
  jlogCallback_destroy(jlogCallbackHandle_t *l)
***************
*** 53,56 ****
--- 67,76 ----
  }
  
+ /**
+  * set the notification levels you want
+  *
+  * @returns 0 upon success
+  * @returns -1 if specified module does not exist
+  */
  int
  jlogCallback_setNotificationLevel(jlogCallbackHandle_t *cbHandle,
***************
*** 77,81 ****
   * register an event callback.
   *
!  * returns -1 on malloc failure
   */
  int
--- 97,102 ----
   * register an event callback.
   *
!  * @returns 0 upon success
!  * @returns -1 on malloc failure
   */
  int
***************
*** 117,120 ****
--- 138,147 ----
  }
  
+ /**
+  * unregister an event callback
+  *
+  * @returns 0 upon success
+  * @returns -1 if specified cb wasn't registered
+  */
  int
  jlog_unregisterEventCallback(jlogHandle_t *logh,
***************
*** 145,149 ****
  static long closes_ever_g=0;	/* number of times log_close succeeded */
  
! /** create a new log handle, or note the re-use of an existing
   * log handle. If reuseh is not NULL, reference count of logh is
   * incremented and returned.
--- 172,177 ----
  static long closes_ever_g=0;	/* number of times log_close succeeded */
  
! /**
!  * create a new log handle, or note the re-use of an existing
   * log handle. If reuseh is not NULL, reference count of logh is
   * incremented and returned.
***************
*** 395,401 ****
  }
  
! /** destroy an log handle, decrements the reference count by one, and
   * frees the resources associated with logh if the reference count reaches
   * zero.
   * returns -1 if logh is invalid
   */
--- 423,431 ----
  }
  
! /**
!  * Destroy an log handle, decrements the reference count by one, and
   * frees the resources associated with logh if the reference count reaches
   * zero.
+  *
   * returns -1 if logh is invalid
   */
***************
*** 470,474 ****
  }
  
! /** get the last module error number
   * returns MOD_ALL if logh is invalid.
   * returns MOD_NONE if no error has been reported since log_open or log_reset
--- 500,505 ----
  }
  
! /**
!  * get the last module error number
   * returns MOD_ALL if logh is invalid.
   * returns MOD_NONE if no error has been reported since log_open or log_reset
***************
*** 487,493 ****
  }
  
! /** get the last reported messageNumber
   * @returns -1 if logh is invalid, or last occuring messageNumber
!    
   * Value of messageNumber is dependent on a module that set it. For instance
   * for a particular module, messageNumber may be an index into a more useful
--- 518,525 ----
  }
  
! /**
!  * get the last reported messageNumber
   * @returns -1 if logh is invalid, or last occuring messageNumber
!  *
   * Value of messageNumber is dependent on a module that set it. For instance
   * for a particular module, messageNumber may be an index into a more useful
***************
*** 507,510 ****
--- 539,546 ----
  }
  
+ /**
+  * reset all what jlog_messageModule and jlog_messageNumber
+  * values would be to MOD_NONE and 0 respectively.
+  */
  int
  jlog_reset(jlogHandle_t *logh)
***************
*** 541,544 ****
--- 577,583 ----
  }*/
  
+ /**
+  * real worker
+  */
  static int
  localfmt(jlogHandle_t *logh,
***************
*** 765,768 ****
--- 804,810 ----
  }
  
+ /**
+  * function enter callback
+  */
  int
  jlog_enter(jlogHandle_t *logh,
***************
*** 785,788 ****
--- 827,833 ----
  }
  
+ /**
+  * function success callback
+  */
  int
  jlog_success(jlogHandle_t *logh,
***************
*** 805,808 ****
--- 850,856 ----
  }
  
+ /**
+  * function failure callback
+  */
  int
  jlog_failure(jlogHandle_t *logh,

Index: jlog2File.c
===================================================================
RCS file: /cvsroot/libimdb/libimdb/libjlog/jlog2File.c,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** jlog2File.c	21 Aug 2003 22:45:18 -0000	1.2
--- jlog2File.c	28 Aug 2003 15:25:00 -0000	1.3
***************
*** 100,103 ****
--- 100,110 ----
  }
  
+ /**
+  * allocate a new jlog2File_t handle which when used with jlog_registerEventCallback,
+  * allows for easy redirection of jlog events to a file.
+  * 
+  * @returns jlog2File_t handle upon success
+  * @returns NULL on malloc failure
+  */
  jlog2File_t *
  jlog2File_create(char *filename)
***************
*** 130,133 ****
--- 137,145 ----
  }
  
+ /**
+  * disable and unallocate a jlog2File handle
+  *
+  * @returns 0 always
+  */
  int
  jlog2File_destroy(jlog2File_t *lt)
***************
*** 139,142 ****
--- 151,161 ----
  }
  
+ /**
+  * enable the jlog2File, this causes redirection to the
+  * specified file (or stdout) to start.
+  *
+  * @returns 0 upon success
+  * @returns -1 if opening file with flags O_CREAT|O_RDWR|O_APPEND and mode 0660 failed.
+  */
  int
  jlog2File_enable(jlog2File_t *lt)
***************
*** 157,160 ****
--- 176,185 ----
  }
  
+ /**
+  * disable redirection to file
+  *
+  * @returns 0 upon success
+  * @returns -1 if close on open file failed
+  */
  int
  jlog2File_disable(jlog2File_t *lt)
***************
*** 174,177 ****
--- 199,205 ----
  }
  
+ /**
+  * get filename
+  */
  char *
  jlog2File_getFilename(jlog2File_t *lt)
***************
*** 180,183 ****
--- 208,215 ----
  }
  
+ /**
+  * get jlogCallbackHandle_t for use with
+  * jlog_registerEventCallback().
+  */
  jlogCallbackHandle_t *
  jlog2File_getJLogCallbackHandle(jlog2File_t *lt)

Index: jlogTracker.c
===================================================================
RCS file: /cvsroot/libimdb/libimdb/libjlog/jlogTracker.c,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** jlogTracker.c	16 Jun 2003 04:18:38 -0000	1.1
--- jlogTracker.c	28 Aug 2003 15:25:00 -0000	1.2
***************
*** 21,45 ****
  #include "jlog/jlogTracker.h"
  
! 
  struct jlogTracker_s {
      struct messHead_s *head;	/**< message stack */
!     
!     jlogCallbackHandle_t *cb;
  };
  
  struct messNode_s {
!     char *srcfile;
!     char *srcfunc;
!     int srcline;
!     jlogModule_e module;
!     jlogReportLevel_e reportLevel;
!     int messageNumber;
!     char *messageText;
!     struct messNode_s *next;
  };
  
  struct messHead_s {
!     int count;
!     struct messNode_s *first;
  };
  
--- 21,49 ----
  #include "jlog/jlogTracker.h"
  
! /**
!  * management structure for internal state information
!  * for jlogTracker_t to work
!  */
  struct jlogTracker_s {
      struct messHead_s *head;	/**< message stack */
!     jlogCallbackHandle_t *cb;	/**< jlog callback handle */
  };
  
+ /** local management structure for a single message */
  struct messNode_s {
!     char *srcfile;		/**< source file */
!     char *srcfunc;		/**< source function */
!     int srcline;		/**< source line number */
!     jlogModule_e module;	/**< module message associated with  */
!     jlogReportLevel_e reportLevel; /**< reporting level of message */
!     int messageNumber;		/**< message number */
!     char *messageText;		/**< message text */
!     struct messNode_s *next;	/**< next message in queue */
  };
  
+ /** local management structure for message queue */
  struct messHead_s {
!     int count;			/**< number of messages */
!     struct messNode_s *first;	/**< pointer to first message  */
  };
  
***************
*** 147,150 ****
--- 151,157 ----
  }
  
+ /**
+  * allocate new jlogTracker_t handle for use.
+  */
  jlogTracker_t *
  jlogTracker_create(void)