doxygen comments

src/libsrc/evio.c

@@ -83,7 +83,8 @@
 
 /* This is necessary to use an error check version of the pthread mutex */
 #ifndef __APPLE__
-#define _GNU_SOURCE
+    /** Enable GNU extensions to C lib such as strdup, strndup, asprintf, pid_t. */
+    #define _GNU_SOURCE
 #endif
 
 #include <stdio.h>
@@ -103,14 +104,23 @@
 
 
 /* A few items to make the code more readable */
+
+/** Read from a file. */
 #define EV_READFILE     0
+/** Read from a pipe. */
 #define EV_READPIPE     1
+/** Read from a socket. */
 #define EV_READSOCK     2
+/** Read from a buffer. */
 #define EV_READBUF      3
 
+/** Write to a file. */
 #define EV_WRITEFILE    4
+/** Write to a pipe. */
 #define EV_WRITEPIPE    5
+/** Write to a socket. */
 #define EV_WRITESOCK    6
+/** Write to a buffer. */
 #define EV_WRITEBUF     7
 
 
@@ -737,21 +747,21 @@ static  int      memoryMapFile(EVFILE *a, const char *fileName);
 static  int      generatePointerTable(EVFILE *a);
 static  int      generatePointerTableV6(EVFILE *a);
 
-/* Array that holds all pointers to structures created with evOpen().
+/** Array that holds all pointers to structures created with evOpen().
  * Space in the array is allocated as needed, beginning with 100
  * and adding 50% every time more are needed. */
 EVFILE **handleList = NULL;
-/* The number of handles available for use. */
+/** The number of handles available for use. */
 static size_t handleCount = 0;
 
-/* Pthread mutex for serializing calls to get and free handles. */
+/** Pthread mutex for serializing calls to get and free handles. */
 #ifdef __APPLE__
 static pthread_mutex_t getHandleMutex = PTHREAD_ERRORCHECK_MUTEX_INITIALIZER;
 #else
 static pthread_mutex_t getHandleMutex = PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP;
 #endif
 
-/* Array of pthread lock pointers for preventing simultaneous calls
+/** Array of pthread lock pointers for preventing simultaneous calls
  * to evClose, read/write routines, etc. Need 1 for each evOpen() call. */
 static pthread_mutex_t **handleLocks = NULL;
 
@@ -2098,7 +2108,7 @@ int evOpenSocket(int sockFd, char *flags, int *handle)
 /** @} */
 
 
-/* For test purposes only ... */
+/** For test purposes only ... */
 int evOpenFake(char *filename, char *flags, int *handle, char **evf)
 {
     EVFILE *a;

src/libsrc/evio.h

@@ -68,7 +68,7 @@ extern "C" {
  * @{
  */
 
-/* macros for swapping ints of various sizes */
+/** Macro for swapping 64 bit ints. */
 #define EVIO_SWAP64(x) ( (((x) >> 56) & 0x00000000000000FFL) | \
                          (((x) >> 40) & 0x000000000000FF00L) | \
                          (((x) >> 24) & 0x0000000000FF0000L) | \
@@ -78,11 +78,13 @@ extern "C" {
                          (((x) << 40) & 0x00FF000000000000L) | \
                          (((x) << 56) & 0xFF00000000000000L) )
 
+/** Macro for swapping 32 bit ints. */
 #define EVIO_SWAP32(x) ( (((x) >> 24) & 0x000000FF) | \
                          (((x) >> 8)  & 0x0000FF00) | \
                          (((x) << 8)  & 0x00FF0000) | \
                          (((x) << 24) & 0xFF000000) )
 
+/** Macro for swapping 16 bit ints. */
 #define EVIO_SWAP16(x) ( (((x) >> 8) & 0x00FF) | \
                          (((x) << 8) & 0xFF00) )
 
@@ -206,7 +208,7 @@ typedef struct evfilestruct {
 
 
     /* dictionary */
-    int   hasAppendDictionary;
+    int   hasAppendDictionary;  /**< if appending, true if first header says there is a dictionary. */
     int   wroteDictionary;      /**< dictionary already written out to a single (split fragment) file? */
     uint32_t dictLength;        /**< length of dictionary bank in bytes (including entire header). */
     uint32_t *dictBuf;          /**< buffer containing dictionary bank. */

src/libsrc/eviofmtdump.c

@@ -43,12 +43,13 @@
 #define SWAP32(x) (x)
 #define SWAP16(x) (x)
 
+/** Struct used to track using the data format. */
 typedef struct
 {
-  int left;    /* index of ifmt[] element containing left parenthesis */
-  int nrepeat; /* how many times format in parenthesis must be repeated */
-  int irepeat; /* right parenthesis counter, or how many times format
-                  in parenthesis already repeated */
+  int left;    /**< index of ifmt[] element containing left parenthesis. */
+  int nrepeat; /**< how many times format in parenthesis must be repeated. */
+  int irepeat; /**< right parenthesis counter, or how many times format
+                    in parenthesis already repeated. */
 } LV;
 
 
@@ -59,6 +60,26 @@ typedef struct
 #define NWORDS 1000000
 static int32_t iarr[NWORDS+10];
 
+
+/**
+ *    This function dumps data into an XML array.
+ *
+ *      Converts the data of array (iarr[i], i=0...nwrd-1)
+ *      using the format code      ifmt[j], j=0...nfmt-1).
+ *
+ *   Algorithm description:
+ *      data processed inside while(ib < nwrd) loop, where 'ib' is iarr[] index; loop breaks when 'ib'
+ *      reaches the number of elements in iarr[].
+ *
+ *
+ * @param arr data array (words).
+ * @param nwrd length of data array in words.
+ * @param ifmt format (as produced by eviofmt.c)
+ * @param nfmt the number of elements in ifmt[]
+ * @param nextrabytes number of extra bytes at the end of the data.
+ * @param xml filled with number of chars printed.
+ * @return the number of bytes in 'xml' if everything fine, negative if error.
+ */
 int
 eviofmtdump(int32_t *arr, int nwrd, unsigned short *ifmt, int nfmt, int nextrabytes, char *xml)
 {