Fix a bunch of undocumented-warnings from Doxygen

No functional changes, just docs.

include/rpm/rpmbase64.h

@@ -13,7 +13,8 @@
 extern "C" {
 #endif
 
-/* returns malloced base64 encoded string
+/**
+ * returns malloced base64 encoded string
  * lines are split with \n characters to be nearest lower multiple of linelen
  * if linelen/4 == 0 lines are not split
  * if linelen < 0 default line length (64) is used
@@ -22,7 +23,8 @@ extern "C" {
  */
 char *rpmBase64Encode(const void *data, size_t len, int linelen);
 
-/* decodes from zero terminated base64 encoded string to a newly malloced buffer
+/**
+ * decodes from zero terminated base64 encoded string to a newly malloced buffer
  * ignores whitespace characters in the input string
  * return values:
  *  0 - OK
@@ -33,7 +35,8 @@ char *rpmBase64Encode(const void *data, size_t len, int linelen);
  */
 int rpmBase64Decode(const char *in, void **out, size_t *outlen);
 
-/* counts CRC24 and base64 encodes it in a malloced string
+/**
+ * counts CRC24 and base64 encodes it in a malloced string
  * returns NULL on failures
  */
 char *rpmBase64CRC(const unsigned char *data, size_t len);

include/rpm/rpmdb.h

@@ -77,6 +77,9 @@ unsigned int rpmdbGetIteratorOffset(rpmdbMatchIterator mi);
 int rpmdbGetIteratorCount(rpmdbMatchIterator mi);
 
 /** \ingroup rpmdb
+ * Return index to the array of elements (eg files) being iterated.
+ * @param mi		rpm database iterator
+ * @return		array index
  */
 unsigned int rpmdbGetIteratorFileNum(rpmdbMatchIterator mi);
 

include/rpm/rpmfc.h

@@ -14,13 +14,18 @@
 extern "C" {
 #endif
 
+/**
+ * Private.
+ */
 extern int _rpmfc_debug;
 
 /** \ingroup rpmfc
+ * File classifier handle.
  */
 typedef struct rpmfc_s * rpmfc;
 
 /** \ingroup rpmfc
+ * File colors.
  */
 enum FCOLOR_e {
     RPMFC_BLACK			= 0,
@@ -28,7 +33,7 @@ enum FCOLOR_e {
     RPMFC_ELF64			= (1 <<  1),
     RPMFC_ELFMIPSN32		= (1 <<  2),
 #define	RPMFC_ELF	(RPMFC_ELF32|RPMFC_ELF64|RPMFC_ELFMIPSN32)
-	/* (1 << 3) leaks into package headers, reserved */
+	/*!< (1 << 3) leaks into package headers, reserved */
 
     RPMFC_WHITE			= (1 << 29),
     RPMFC_INCLUDE		= (1 << 30),

include/rpm/rpmfileutil.h

@@ -15,6 +15,7 @@ extern "C" {
 #endif
 
 /** \ingroup rpmfileutil
+ * Compression types detected by rpm (subject to build configuration).
  */
 typedef enum rpmCompressedMagic_e {
     COMPRESSED_NOT		= 0,	/*!< not compressed */

include/rpm/rpmio.h

@@ -21,10 +21,9 @@ extern "C" {
 #endif
 
 /** \ingroup rpmio
- */
+*/
 typedef const struct FDIO_s * FDIO_t;
 
-
 /** \ingroup rpmio
  * \name RPMIO Interface.
  */
@@ -152,22 +151,27 @@ const char * Fdescr(FD_t fd);
  */
 
 /** \ingroup rpmio
+ * Return the size of the backing file of the descriptor.
  */
 off_t	fdSize(FD_t fd);
 
 /** \ingroup rpmio
+ * dup(2) clone.
  */
 FD_t fdDup(int fdno);
 
 /** \ingroup rpmio
+ * Reference a file descriptor.
  */
 FD_t fdLink(FD_t fd);
 
 /** \ingroup rpmio
+ * Dereference a file descriptor. This does NOT close the file.
  */
 FD_t fdFree(FD_t fd);
 
 /**
+ * Copy file descriptor into another.
  */
 off_t ufdCopy(FD_t sfd, FD_t tfd);
 
@@ -184,7 +188,7 @@ typedef enum fdOpX_e {
 } fdOpX;
 
 /** \ingroup rpmio
- *
+ * File operation statistics.
  */
 rpmop fdOp(FD_t fd, fdOpX opx);
 

include/rpm/rpmmacro.h

@@ -132,6 +132,8 @@ int	rpmPushMacroFlags	(rpmMacroContext mc, const char * n,
  * @param o		macro parameters (or NULL)
  * @param f		macro function
  * @param priv		private user data (or NULL)
+ * @param nargs		number of arguments (0-N for enforced check,
+ *			-1 for optional)
  * @param level		macro recursion level (0 is entry API)
  * @param flags		macro flags
  * @return		0 on success
@@ -189,7 +191,7 @@ int	rpmPopMacro	(rpmMacroContext mc, const char * n);
 int	rpmDefineMacro	(rpmMacroContext mc, const char * macro,
 				int level);
 
-/*
+/**
  * Test whether a macro is defined
  * @param mc		macro context (NULL uses global context).
  * @param n		macro name
@@ -197,7 +199,7 @@ int	rpmDefineMacro	(rpmMacroContext mc, const char * macro,
  */
 int rpmMacroIsDefined(rpmMacroContext mc, const char *n);
 
-/*
+/**
  * Test whether a macro is parametric (ie takes arguments)
  * @param mc		macro context (NULL uses global context).
  * @param n		macro name

include/rpm/rpmsign.h

@@ -22,9 +22,9 @@ enum rpmSignFlags_e {
 typedef rpmFlags rpmSignFlags;
 
 struct rpmSignArgs {
-    char *keyid;
-    pgpHashAlgo hashalgo;
-    rpmSignFlags signflags;
+    char *keyid;		/*!< signer keyid */
+    pgpHashAlgo hashalgo;	/*!< hash algorithm to use */
+    rpmSignFlags signflags;	/*!< flags to control operation */
     /* ... what else? */
 };
 

include/rpm/rpmsw.h

@@ -33,7 +33,7 @@ struct rpmsw_s {
 	struct timeval tv;
 	unsigned long long int ticks;
 	unsigned long int tocks[2];
-    } u;
+    } u; /*!< Private */
 };
 
 /** \ingroup rpmsw

include/rpm/rpmtd.h

@@ -14,6 +14,9 @@
 extern "C" {
 #endif
 
+/**
+ * Flags potentially present in rpmtd struct.
+ */
 enum rpmtdFlags_e {
     RPMTD_NONE		= 0,
     RPMTD_ALLOCED	= (1 << 0),	/* was memory allocated? */
@@ -30,13 +33,13 @@ typedef rpmFlags rpmtdFlags;
  * @todo		Make this opaque (at least outside rpm itself)
  */
 struct rpmtd_s {
-    rpm_tag_t tag;	/* rpm tag of this data entry*/
-    rpm_tagtype_t type;	/* data type */
-    rpm_count_t count;	/* number of entries */
-    rpm_data_t data;	/* pointer to actual data */
-    rpmtdFlags flags;	/* flags on memory allocation etc */
-    int ix;		/* iteration index */
-    rpm_count_t size;	/* size of data (only works for RPMTD_IMMUTABLE atm) */
+    rpm_tag_t tag;	/*!< rpm tag of this data entry*/
+    rpm_tagtype_t type;	/*!< data type */
+    rpm_count_t count;	/*!< number of entries */
+    rpm_data_t data;	/*!< pointer to actual data */
+    rpmtdFlags flags;	/*!< flags on memory allocation etc */
+    int ix;		/*!< iteration index */
+    rpm_count_t size;	/*!< size of data (only works for RPMTD_IMMUTABLE atm) */
 };
 
 /** \ingroup rpmtd
@@ -222,6 +225,9 @@ const char * rpmtdGetString(rpmtd td);
  */
 uint64_t rpmtdGetNumber(rpmtd td);
 
+/**
+ * Formats supported by rpmtdFormat().
+ */
 typedef enum rpmtdFormats_e {
     RPMTD_FORMAT_STRING		= 0,	/* plain string (any type) */
     RPMTD_FORMAT_ARMOR		= 1,	/* ascii armor format (bin types) */