Doxygen annotations.

CVS patchset: 4132
CVS date: 2000/08/27 19:27:03

41 files changed, 979 insertions, 430 deletions

diff --git a/lib/depends.c b/lib/depends.c
index a85af91bc..95e84e7ed 100644
--- a/lib/depends.c
+++ b/lib/depends.c
@@ -1,5 +1,9 @@
 #include "system.h"
 
+/** \ingroup rpmdep
+ * \file lib/depends.c
+ */
+
 #include <rpmlib.h>
 
 #include "depends.h"
diff --git a/lib/depends.h b/lib/depends.h
index 9bdc0b5e5..3c1b9af59 100644
--- a/lib/depends.h
+++ b/lib/depends.h
@@ -1,6 +1,10 @@
 #ifndef H_DEPENDS
 #define H_DEPENDS
 
+/** \file lib/depends.h
+ *
+ */
+
 #include <header.h>
 
 /**
diff --git a/lib/falloc.c b/lib/falloc.c
index ea28a528f..c532d8602 100644
--- a/lib/falloc.c
+++ b/lib/falloc.c
@@ -1,21 +1,26 @@
 #include "system.h"
 
+/** \ingroup rpmio db1
+ * \file lib/falloc.c
+ * 
+ * The entire file space is thus divided into blocks with a "struct fablock"
+ * at the header of each. The size fields doubly link this block list.
+ *
+ * There is an additional free list weaved through the block list, which 
+ * keeps new allocations fast.
+ *
+ * Much of this was inspired by Knuth vol 1.
+ *
+ */
+
 #include <rpmio_internal.h>
 #include "falloc.h"
 
-#define FA_MAGIC      0x02050920
-
-/* 
-   The entire file space is thus divided into blocks with a "struct fablock"
-   at the header of each. The size fields doubly link this block list.
-
-   There is an additional free list weaved through the block list, which 
-   keeps new allocations fast.
-
-   Much of this was inspired by Knuth vol 1.
+/** \ingroup db1
  */
+#define FA_MAGIC      0x02050920
 
-struct faFileHeader{
+struct faFileHeader {
     unsigned int magic;
     unsigned int firstFree;
 };
diff --git a/lib/falloc.h b/lib/falloc.h
index c7c89ebaf..846868101 100644
--- a/lib/falloc.h
+++ b/lib/falloc.h
@@ -1,11 +1,16 @@
 #ifndef H_FALLOC
 #define H_FALLOC
 
-/*@access FD_t@*/
+/** \ingroup db1
+ * \file lib/falloc.h
+ * File space allocation routines.
+ *
+ * Best fit allocation is used, free blocks are compacted. Minimal
+ * fragmentation is more important then speed. This uses 32 bit
+ * offsets on all platforms and should be byte order independent.
+ */
 
-/* File space allocation routines. Best fit allocation is used, free blocks
-   are compacted. Minimal fragmentation is more important then speed. This
-   uses 32 bit offsets on all platforms and should be byte order independent */
+/*@access FD_t@*/
 
 #ifdef __cplusplus
 extern "C" {
@@ -27,11 +32,28 @@ extern "C" {
     fd->firstFree = firstFree;
 }
 
+/** \ingroup db1
+ */
 /*@null@*/ FD_t	fadOpen		(const char * path, int flags, mode_t perms);
+
+/** \ingroup db1
+ * @param fd			file handle
+ */
 unsigned int	fadAlloc	(FD_t fd, unsigned int size); /* 0 on failure */
+
+/** \ingroup db1
+ * @param fd			file handle
+ */
 void		fadFree		(FD_t fd, unsigned int offset);
 
+/** \ingroup db1
+ * @param fd			file handle
+ */
 int		fadFirstOffset	(FD_t fd);
+
+/** \ingroup db1
+ * @param fd			file handle
+ */
 int		fadNextOffset	(FD_t fd, unsigned int lastoff); /* 0 at end */
 
 #ifdef __cplusplus
diff --git a/lib/fileutil.c b/lib/fileutil.c
index b0082d230..2c3aa70b7 100644
--- a/lib/fileutil.c
+++ b/lib/fileutil.c
@@ -1,5 +1,9 @@
 #include "system.h"
 
+/**
+ * \file lib/fileutil.c
+ */
+
 #include <rpmlib.h>
 
 #include "misc.h"
diff --git a/lib/formats.c b/lib/formats.c
index 5e40f49bd..cd8066744 100644
--- a/lib/formats.c
+++ b/lib/formats.c
@@ -1,5 +1,9 @@
 #include "system.h"
 
+/** \ingroup header
+ * \file lib/formats.c
+ */
+
 #include <rpmlib.h>
 #include <rpmmacro.h>	/* XXX for %_i18ndomains */
 #include "misc.h"
diff --git a/lib/fprint.c b/lib/fprint.c
index 3e593f5b1..65f705907 100644
--- a/lib/fprint.c
+++ b/lib/fprint.c
@@ -1,5 +1,9 @@
 #include "system.h"
 
+/**
+ * \file lib/fprint.c
+ */
+
 #include <rpmlib.h>
 #include <rpmmacro.h>	/* XXX for rpmCleanPath */
 
diff --git a/lib/fs.c b/lib/fs.c
index d000e0eaf..371a0d3bd 100644
--- a/lib/fs.c
+++ b/lib/fs.c
@@ -1,5 +1,9 @@
 #include "system.h"
 
+/**
+ * \file lib/fs.c
+ */
+
 #include <rpmlib.h>
 #include <rpmmacro.h>
 
diff --git a/lib/hash.h b/lib/hash.h
index eeebae75f..0cd98e08a 100644
--- a/lib/hash.h
+++ b/lib/hash.h
@@ -2,7 +2,7 @@
 #define H_HASH
 
 /** \file lib/hash.h
- * Hash table implemenation
+ * Hash table implemenation.
  */
 
 typedef struct hashTable_s * hashTable;
diff --git a/lib/header.c b/lib/header.c
index 37a4cf8dc..a7cb09c2e 100644
--- a/lib/header.c
+++ b/lib/header.c
@@ -1,8 +1,9 @@
-/* RPM - Copyright (C) 1995 Red Hat Software
- *
- * header.c - routines for managing rpm headers
+/** \ingroup header
+ * \file lib/header.c
  */
 
+/* RPM - Copyright (C) 1995 Red Hat Software */
+
 /* Data written to file descriptors is in network byte order.    */
 /* Data read from file descriptors is expected to be in          */
 /* network byte order and is converted on the fly to host order. */
@@ -40,7 +41,8 @@ static int typeSizes[] =  {
 	/* RPM_STRING_TYPE */		-1,
 	/* RPM_BIN_TYPE */		1,
 	/* RPM_STRING_ARRAY_TYPE */	-1,
-	/* RPM_I18NSTRING_TYPE */	-1 };
+	/* RPM_I18NSTRING_TYPE */	-1
+};
 
 struct headerToken {
     struct indexEntry *index;
@@ -48,7 +50,7 @@ struct headerToken {
     int indexAlloced;
 
     int sorted;  
-    /*@refs@*/ int usageCount;
+/*@refs@*/ int usageCount;
 };
 
 struct entryInfo {
@@ -61,7 +63,7 @@ struct entryInfo {
 
 struct indexEntry {
     struct entryInfo info;
-    /*@owned@*/ void * data; 
+/*@owned@*/ void * data; 
     int length;			/* Computable, but why bother? */
 };
 
@@ -72,8 +74,8 @@ struct sprintfTag {
     int_32 tag;
     int justOne;
     int arrayCount;
-    char * format;
-    char * type;
+/*@kept@*/ char * format;
+/*@kept@*/ char * type;
     int pad;
 };
 
@@ -82,7 +84,7 @@ struct extensionCache {
     int_32 count;
     int avail;
     int freeit;
-    const void * data;
+/*@owned@*/ const void * data;
 };
 
 struct sprintfToken {
@@ -155,8 +157,9 @@ static void headerProbe(Header h, const char *msg)
 #define	HEADERPROBE(_h, _msg)
 #endif	/* HAVE_MCHECK_H */
 
-static void copyEntry(struct indexEntry * entry, /*@out@*/ int_32 * type,
+static void copyEntry(const struct indexEntry * entry, /*@out@*/ int_32 * type,
 	/*@out@*/ void ** p, /*@out@*/ int_32 * c, int minimizeMemory)
+		/*@modifies *type, *p, *c @*/
 {
     int i, tableSize;
     char ** ptrEntry;
@@ -203,6 +206,7 @@ static void copyEntry(struct indexEntry * entry, /*@out@*/ int_32 * type,
 }
 
 static int dataLength(int_32 type, const void * p, int_32 count, int onDisk)
+	/*@*/
 {
     int thisLen, length, i;
     char ** src, * chptr;
@@ -303,7 +307,7 @@ int headerNextIterator(HeaderIterator iter,
     return 1;
 }
 
-static int indexCmp(const void *ap, const void *bp)
+static int indexCmp(const void *ap, const void *bp)	/*@*/
 {
     int_32 a = ((const struct indexEntry *)ap)->info.tag;
     int_32 b = ((const struct indexEntry *)bp)->info.tag;
@@ -427,6 +431,7 @@ Header headerLoad(void *pv)
 }
 
 static void *doHeaderUnload(Header h, /*@out@*/int * lengthPtr)
+	/*@modifies h, *lengthPtr @*/
 {
     int i;
     int type, diff;
@@ -735,6 +740,7 @@ void headerDump(Header h, FILE *f, int flags,
 /********************************************************************/
 
 static struct indexEntry *findEntry(Header h, int_32 tag, int_32 type)
+	/*@modifies h @*/
 {
     struct indexEntry * entry, * entry2, * last;
     struct indexEntry key;
@@ -792,6 +798,7 @@ int headerGetRawEntry(Header h, int_32 tag, int_32 *type, void **p, int_32 *c)
 }
 
 static int headerMatchLocale(const char *td, const char *l, const char *le)
+	/*@*/
 {
     const char *fe;
 
@@ -909,6 +916,7 @@ headerFindI18NString(Header h, struct indexEntry *entry)
 
 static int intGetEntry(Header h, int_32 tag, /*@out@*/ int_32 *type,
 	/*@out@*/ void **p, /*@out@*/ int_32 *c, int minMem)
+		/*@modifies h, *type, *p, *c @*/
 {
     struct indexEntry * entry;
     char * chptr;
@@ -928,7 +936,7 @@ static int intGetEntry(Header h, int_32 tag, /*@out@*/ int_32 *type,
 	if (type) *type = RPM_STRING_TYPE;
 	if (c) *c = 1;
 
-	*p = chptr;
+	/*@-dependenttrans@*/ *p = chptr; /*@=dependenttrans@*/
     } else {
 	copyEntry(entry, type, p, c, minMem);
     }
@@ -983,7 +991,7 @@ Header headerLink(Header h)
 {
     HEADERPROBE(h, "headerLink");
     h->usageCount++;
-    return h;
+    /*@-refcounttrans@*/ return h; /*@=refcounttrans@*/
 }
 
 int headerUsageCount(Header h)
@@ -1020,8 +1028,9 @@ unsigned int headerSizeof(Header h, int magicp)
     return size;
 }
 
-static void copyData(int_32 type, /*@out@*/void * dstPtr, const void * srcPtr, int_32 c, 
-			int dataLength)
+static void copyData(int_32 type, /*@out@*/ void * dstPtr, const void * srcPtr,
+	int_32 c, int dataLength)
+		/*@modifies *dstPtr @*/
 {
     const char ** src;
     char * dst;
@@ -1048,7 +1057,9 @@ static void copyData(int_32 type, /*@out@*/void * dstPtr, const void * srcPtr, i
     }
 }
 
-static void * grabData(int_32 type, const void * p, int_32 c, int * lengthPtr)
+static void * grabData(int_32 type, const void * p, int_32 c,
+	/*@out@*/ int * lengthPtr)
+		/*@modifies *lengthPtr @*/
 {
     int length;
     void * data;
@@ -1138,7 +1149,7 @@ int headerAddI18NString(Header h, int_32 tag, const char * string, const char *
 	return 0;		/* this shouldn't ever happen!! */
 
     if (!table && !entry) {
-	const char * charArray[2];
+	errmsg_t charArray[2];
 	int count = 0;
 	if (!lang || (lang[0] == 'C' && lang[1] == '\0')) {
 	    charArray[count++] = "C";
@@ -1287,7 +1298,7 @@ int headerAppendEntry(Header h, int_32 tag, int_32 type, void * p, int_32 c)
 
     entry->info.count += c;
 
-    return 0;
+    return 1;
 }
 
 int headerRemoveEntry(Header h, int_32 tag)
@@ -1322,7 +1333,7 @@ int headerRemoveEntry(Header h, int_32 tag)
     return 0;
 }
 
-static char escapedChar(const char ch)
+static char escapedChar(const char ch)	/*@*/
 {
     switch (ch) {
     case 'a': 	return '\a';
@@ -1365,6 +1376,7 @@ static void findTag(char * name, const struct headerTagTableEntry * tags,
 		    const struct headerSprintfExtension * extensions,
 		    /*@out@*/const struct headerTagTableEntry ** tagMatch,
 		    /*@out@*/const struct headerSprintfExtension ** extMatch)
+	/*@modifies *tagMatch, *extMatch @*/
 {
     const struct headerTagTableEntry * entry;
     const struct headerSprintfExtension * ext;
@@ -1412,12 +1424,14 @@ static void findTag(char * name, const struct headerTagTableEntry * tags,
 static int parseExpression(struct sprintfToken * token, char * str, 
 	const struct headerTagTableEntry * tags, 
 	const struct headerSprintfExtension * extensions,
-	/*@out@*/char ** endPtr, /*@out@*/const char ** error);
+	/*@out@*/char ** endPtr, /*@out@*/ errmsg_t * errmsg)
+		/*@modifies str, *str, *token, *endPtr, *errmsg @*/;
 
 static int parseFormat(char * str, const struct headerTagTableEntry * tags,
 	const struct headerSprintfExtension * extensions,
 	/*@out@*/struct sprintfToken ** formatPtr, /*@out@*/int * numTokensPtr,
-	/*@out@*/char ** endPtr, int state, /*@out@*/const char ** error)
+	/*@out@*/char ** endPtr, int state, /*@out@*/ errmsg_t * errmsg)
+	  /*@modifies str, *str, *formatPtr, *numTokensPtr, *endPtr, *errmsg @*/
 {
     char * chptr, * start, * next, * dst;
     struct sprintfToken * format;
@@ -1439,7 +1453,7 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags,
 
     dst = start = str;
     currToken = -1;
-    while (*start && !done) {
+    while (*start) {
 	switch (*start) {
 	case '%':
 	    /* handle %% */
@@ -1466,7 +1480,7 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags,
 
 		start++;
 		if (parseExpression(format + currToken, start, tags, 
-				    extensions, &newEnd, error)) {
+				    extensions, &newEnd, errmsg)) {
 		    freeFormat(format, numTokens);
 		    return 1;
 		}
@@ -1482,7 +1496,7 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags,
 	    chptr = start;
 	    while (*chptr && *chptr != '{' && *chptr != '%') chptr++;
 	    if (!*chptr || *chptr == '%') {
-		*error = _("missing { after %");
+		*errmsg = _("missing { after %");
 		freeFormat(format, numTokens);
 		return 1;
 	    }
@@ -1510,7 +1524,7 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags,
 	    next = start;
 	    while (*next && *next != '}') next++;
 	    if (!*next) {
-		*error = _("missing } after %{");
+		*errmsg = _("missing } after %{");
 		freeFormat(format, numTokens);
 		return 1;
 	    }
@@ -1522,7 +1536,7 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags,
 	    if (*chptr) {
 		*chptr++ = '\0';
 		if (!*chptr) {
-		    *error = _("empty tag format");
+		    *errmsg = _("empty tag format");
 		    freeFormat(format, numTokens);
 		    return 1;
 		}
@@ -1532,7 +1546,7 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags,
 	    }
 	    
 	    if (!*start) {
-		*error = _("empty tag name");
+		*errmsg = _("empty tag name");
 		freeFormat(format, numTokens);
 		return 1;
 	    }
@@ -1547,7 +1561,7 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags,
 		format[currToken].u.tag.ext = ext->u.tagFunction;
 		format[currToken].u.tag.extNum = ext - extensions;
 	    } else {
-		*error = _("unknown tag");
+		*errmsg = _("unknown tag");
 		freeFormat(format, numTokens);
 		return 1;
 	    }
@@ -1566,13 +1580,13 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags,
 	    if (parseFormat(start, tags, extensions, 
 			    &format[currToken].u.array.format,
 			    &format[currToken].u.array.numTokens,
-			    &start, PARSER_IN_ARRAY, error)) {
+			    &start, PARSER_IN_ARRAY, errmsg)) {
 		freeFormat(format, numTokens);
 		return 1;
 	    }
 
 	    if (!start) {
-		*error = _("] expected at end of array");
+		*errmsg = _("] expected at end of array");
 		freeFormat(format, numTokens);
 		return 1;
 	    }
@@ -1588,9 +1602,9 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags,
 	    if ((*start == ']' && state != PARSER_IN_ARRAY) ||
 	        (*start == '}' && state != PARSER_IN_EXPR)) {
 		if (*start == ']')
-		    *error = _("unexpected ]");
+		    *errmsg = _("unexpected ]");
 		else
-		    *error = _("unexpected }");
+		    *errmsg = _("unexpected }");
 		freeFormat(format, numTokens);
 		return 1;
 	    }
@@ -1614,6 +1628,8 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags,
 	    }
 	    break;
 	}
+	if (done)
+	    break;
     }
 
     *dst = '\0';
@@ -1633,37 +1649,38 @@ static int parseFormat(char * str, const struct headerTagTableEntry * tags,
 static int parseExpression(struct sprintfToken * token, char * str, 
 	const struct headerTagTableEntry * tags, 
 	const struct headerSprintfExtension * extensions,
-	/*@out@*/ char ** endPtr, /*@out@*/ const char ** error)
+	/*@out@*/ char ** endPtr, /*@out@*/ errmsg_t * errmsg)
+		/*@modifies str, *str, *token, *endPtr, *errmsg @*/
 {
     const struct headerTagTableEntry * tag;
     const struct headerSprintfExtension * ext;
     char * chptr;
     char * end;
 
-    *error = NULL;
+    *errmsg = NULL;
     chptr = str;
     while (*chptr && *chptr != '?') chptr++;
 
     if (*chptr != '?') {
-	*error = _("? expected in expression");
+	*errmsg = _("? expected in expression");
 	return 1;
     }
 
     *chptr++ = '\0';;
 
     if (*chptr != '{') {
-	*error = _("{ expected after ? in expression");
+	*errmsg = _("{ expected after ? in expression");
 	return 1;
     }
 
     chptr++;
 
     if (parseFormat(chptr, tags, extensions, &token->u.cond.ifFormat, 
-		    &token->u.cond.numIfTokens, &end, PARSER_IN_EXPR, error)) 
+		    &token->u.cond.numIfTokens, &end, PARSER_IN_EXPR, errmsg)) 
 	return 1;
 
     if (!*end) {
-	*error = _("} expected in expression");
+	*errmsg = _("} expected in expression");
 	freeFormat(token->u.cond.ifFormat, token->u.cond.numIfTokens);
 	token->u.cond.ifFormat = NULL;
 	return 1;
@@ -1671,7 +1688,7 @@ static int parseExpression(struct sprintfToken * token, char * str,
 
     chptr = end;
     if (*chptr != ':' && *chptr != '|') {
-	*error = _(": expected following ? subexpression");
+	*errmsg = _(": expected following ? subexpression");
 	freeFormat(token->u.cond.ifFormat, token->u.cond.numIfTokens);
 	token->u.cond.ifFormat = NULL;
 	return 1;
@@ -1680,12 +1697,12 @@ static int parseExpression(struct sprintfToken * token, char * str,
     if (*chptr == '|') {
 	parseFormat(xstrdup(""), tags, extensions, &token->u.cond.elseFormat, 
 			&token->u.cond.numElseTokens, &end, PARSER_IN_EXPR, 
-			error);
+			errmsg);
     } else {
 	chptr++;
 
 	if (*chptr != '{') {
-	    *error = _("{ expected after : in expression");
+	    *errmsg = _("{ expected after : in expression");
 	    freeFormat(token->u.cond.ifFormat, token->u.cond.numIfTokens);
 	    token->u.cond.ifFormat = NULL;
 	    return 1;
@@ -1695,10 +1712,10 @@ static int parseExpression(struct sprintfToken * token, char * str,
 
 	if (parseFormat(chptr, tags, extensions, &token->u.cond.elseFormat, 
 			&token->u.cond.numElseTokens, &end, PARSER_IN_EXPR, 
-			error)) 
+			errmsg)) 
 	    return 1;
 	if (!*end) {
-	    *error = _("} expected in expression");
+	    *errmsg = _("} expected in expression");
 	    freeFormat(token->u.cond.ifFormat, token->u.cond.numIfTokens);
 	    token->u.cond.ifFormat = NULL;
 	    return 1;
@@ -1706,7 +1723,7 @@ static int parseExpression(struct sprintfToken * token, char * str,
 
 	chptr = end;
 	if (*chptr != '|') {
-	    *error = _("| expected at end of expression");
+	    *errmsg = _("| expected at end of expression");
 	    freeFormat(token->u.cond.ifFormat, token->u.cond.numIfTokens);
 	    token->u.cond.ifFormat = NULL;
 	    freeFormat(token->u.cond.elseFormat, token->u.cond.numElseTokens);
@@ -1740,6 +1757,7 @@ static int parseExpression(struct sprintfToken * token, char * str,
 static int getExtension(Header h, headerTagTagFunction fn,
 	/*@out@*/ int_32 * typeptr, /*@out@*/ const void ** data,
 	/*@out@*/ int_32 * countptr, struct extensionCache * ext)
+		/*@modifies *typeptr, *data, *countptr, ext->avail @*/
 {
     if (!ext->avail) {
 	if (fn(h, &ext->type, &ext->data, &ext->count, &ext->freeit))
@@ -1757,6 +1775,7 @@ static int getExtension(Header h, headerTagTagFunction fn,
 static char * formatValue(struct sprintfTag * tag, Header h, 
 			  const struct headerSprintfExtension * extensions,
 			  struct extensionCache * extCache, int element)
+		/*@modifies h, extCache->avail @*/
 {
     int len;
     char buf[20];
@@ -1881,6 +1900,7 @@ static char * formatValue(struct sprintfTag * tag, Header h,
 static const char * singleSprintf(Header h, struct sprintfToken * token,
 			    const struct headerSprintfExtension * extensions,
 			    struct extensionCache * extCache, int element)
+		/*@modifies h, extCache->avail @*/
 {
     char * val;
     const char * thisItem;
@@ -1993,6 +2013,7 @@ static const char * singleSprintf(Header h, struct sprintfToken * token,
 
 static struct extensionCache * allocateExtensionCache(
 		     const struct headerSprintfExtension * extensions)
+		/*@*/
 {
     const struct headerSprintfExtension * ext = extensions;
     int i = 0;
@@ -2030,7 +2051,7 @@ static void freeExtensionCache(const struct headerSprintfExtension * extensions,
 char * headerSprintf(Header h, const char * origFmt, 
 		     const struct headerTagTableEntry * tags,
 		     const struct headerSprintfExtension * extensions,
-		     const char ** error)
+		     errmsg_t * errmsg)
 {
     char * fmtString;
     struct sprintfToken * format;
@@ -2045,7 +2066,7 @@ char * headerSprintf(Header h, const char * origFmt,
     fmtString = xstrdup(origFmt);
    
     if (parseFormat(fmtString, tags, extensions, &format, &numTokens, 
-		    NULL, PARSER_BEGIN, error)) {
+		    NULL, PARSER_BEGIN, errmsg)) {
 	free(fmtString);
 	return NULL;
     }
@@ -2085,6 +2106,7 @@ char * headerSprintf(Header h, const char * origFmt,
 
 static char * octalFormat(int_32 type, const void * data, 
 		char * formatPrefix, int padding, /*@unused@*/int element)
+		/*@modifies formatPrefix @*/
 {
     char * val;
 
@@ -2101,6 +2123,7 @@ static char * octalFormat(int_32 type, const void * data,
 
 static char * hexFormat(int_32 type, const void * data, 
 		char * formatPrefix, int padding, /*@unused@*/int element)
+		/*@modifies formatPrefix @*/
 {
     char * val;
 
@@ -2118,6 +2141,7 @@ static char * hexFormat(int_32 type, const void * data,
 static char * realDateFormat(int_32 type, const void * data, 
 		char * formatPrefix, int padding, /*@unused@*/int element,
 		char * strftimeFormat)
+		/*@modifies formatPrefix @*/
 {
     char * val;
     struct tm * tstruct;
@@ -2142,12 +2166,14 @@ static char * realDateFormat(int_32 type, const void * data,
 
 static char * dateFormat(int_32 type, const void * data, 
 		         char * formatPrefix, int padding, int element)
+		/*@modifies formatPrefix @*/
 {
     return realDateFormat(type, data, formatPrefix, padding, element, "%c");
 }
 
 static char * dayFormat(int_32 type, const void * data, 
 		         char * formatPrefix, int padding, int element)
+		/*@modifies formatPrefix @*/
 {
     return realDateFormat(type, data, formatPrefix, padding, element, 
 			  "%a %b %d %Y");
@@ -2155,6 +2181,7 @@ static char * dayFormat(int_32 type, const void * data,
 
 static char * shescapeFormat(int_32 type, const void * data, 
 		char * formatPrefix, int padding, /*@unused@*/int element)
+		/*@modifies formatPrefix @*/
 {
     char * result, * dst, * src, * buf;
 
diff --git a/lib/header.h b/lib/header.h
index 2c049ac22..029e1ff92 100644
--- a/lib/header.h
+++ b/lib/header.h
@@ -1,12 +1,14 @@
-/* RPM - Copyright (C) 1995 Red Hat Software
+#ifndef H_HEADER
+#define H_HEADER
+
+/** \file lib/header.h
  *
- * header.h - routines for managing rpm tagged structures
  */
 
+/* RPM - Copyright (C) 1995 Red Hat Software */
+
 /* WARNING: 1 means success, 0 means failure (yes, this is backwards) */
 
-#ifndef H_HEADER
-#define H_HEADER
 #include <stdio.h>
 #include <zlib.h>
 
@@ -39,134 +41,377 @@ typedef unsigned short uint_16;
 typedef /*@abstract@*/ /*@refcounted@*/ struct headerToken *Header;
 typedef /*@abstract@*/ struct headerIteratorS *HeaderIterator;
 
+/** \ingroup header
+ * Associate tag names with numeric values.
+ */
 struct headerTagTableEntry {
-    const char * name;
-    int val;
+    const char * name;		/*!< Tag name. */
+    int val;			/*!< Tag numeric value. */
 };
 
-enum headerSprintfExtenstionType { HEADER_EXT_LAST = 0, HEADER_EXT_FORMAT,
-				   HEADER_EXT_MORE, HEADER_EXT_TAG };
+/** \ingroup header
+ */
+enum headerSprintfExtenstionType {
+	HEADER_EXT_LAST = 0,	/*!< End of extension chain. */
+	HEADER_EXT_FORMAT,	/*!< headerTagFormatFunction() extension */
+	HEADER_EXT_MORE,	/*!< Chain to next table. */
+	HEADER_EXT_TAG		/*!< headerTagTagFunction() extension */
+};
 
-/* This will only ever be passed RPM_TYPE_INT32 or RPM_TYPE_STRING to
-   help keep things simple */
-typedef char * (*headerTagFormatFunction)(int_32 type, const void * data,
-					  char * formatPrefix,
-					  int padding, int element);
-/* This is allowed to fail, which indicates the tag doesn't exist */
+/** \ingroup header
+ * HEADER_EXT_TAG format function prototype.
+ * This will only ever be passed RPM_TYPE_INT32 or RPM_TYPE_STRING to
+ * help keep things simple
+ *
+ * @param type		tag type
+ * @param data		tag value
+ * @param formatPrefix
+ * @param padding
+ * @param element
+ * @return		formatted string
+ */
+typedef /*only@*/ char * (*headerTagFormatFunction)(int_32 type,
+				const void * data, char * formatPrefix,
+				int padding, int element);
+/** \ingroup header
+ * HEADER_EXT_FORMAT format function prototype.
+ * This is allowed to fail, which indicates the tag doesn't exist.
+ *
+ * @param h		header
+ * @retval type		address of tag type
+ * @retval data		address of tag value pointer
+ * @retval count	address of no. of data items
+ * @retval freedata	address of data-was-malloc'ed indicator
+ * @return		0 on success
+ */
 typedef int (*headerTagTagFunction)(Header h, int_32 * type, const void ** data,
 				       int_32 * count, int * freeData);
 
+/** \ingroup header
+ * Define header tag output formats.
+ */
 struct headerSprintfExtension {
-    enum headerSprintfExtenstionType type;
-    char * name;
+    enum headerSprintfExtenstionType type;	/*!< Type of extension. */
+    char * name;				/*!< Name of extension. */
     union {
-	void * generic;
-	headerTagFormatFunction formatFunction;
-	headerTagTagFunction tagFunction;
-	struct headerSprintfExtension * more;
+	void * generic;				/*!< Private extension. */
+	headerTagFormatFunction formatFunction; /*!< HEADER_EXT_TAG extension. */
+	headerTagTagFunction tagFunction;	/*!< HEADER_EXT_FORMAT extension. */
+	struct headerSprintfExtension * more;	/*!< Chained table extension. */
     } u;
 };
 
-/* This defines some basic conversions all header users would probably like
-   to have */
+/** \ingroup header
+ * Supported default header tag output formats.
+ */
 extern const struct headerSprintfExtension headerDefaultFormats[];
 
-/* read and write a header from a file */
-Header headerRead(FD_t fd, int magicp);
-int headerWrite(FD_t fd, Header h, int magicp);
-Header headerGzRead(FD_t fd, int magicp);
-int headerGzWrite(FD_t fd, Header h, int magicp);
-unsigned int headerSizeof(Header h, int magicp);
+/** \ingroup header
+ * Read (and load) header from file handle.
+ * @param fd		file handle
+ * @param magicp
+ * @return		header
+ */
+Header headerRead(FD_t fd, int magicp)	/*@modifies fd @*/;
+
+/** \ingroup header
+ * Write (with unload) header to file handle.
+ * @param fd		file handle
+ * @param h		header
+ * @param magicp
+ * @return
+ */
+int headerWrite(FD_t fd, Header h, int magicp)	/*@modifies fd, h @*/;
+
+/** \ingroup header
+ * Return size of on-disk header representation in bytes.
+ */
+unsigned int headerSizeof(Header h, int magicp)
+	/*@modifies h @*/;
 
 #define HEADER_MAGIC_NO   0
 #define HEADER_MAGIC_YES  1
 
-/* load and unload a header from a chunk of memory */
-Header headerLoad(void *p);
-void *headerUnload(Header h);
+/** \ingroup header
+ * Convert header to in-memory representation.
+ * @param p		on-disk header (with offsets)
+ * @return		header (with pointers)
+ */
+Header headerLoad(void *p)	/*@*/;
+
+/** \ingroup header
+ * Convert header to on-disk representation.
+ * @param h		header (with pointers)
+ * @return		on-disk header (with offsets)
+ */
+void *headerUnload(Header h)
+	/*@modifes h @*/;
+
+/** \ingroup header
+ * Create new (empty) header instance.
+ * @return		header
+ */
+Header headerNew(void)	/*@*/;
+
+/** \ingroup header
+ * Reference a header instance.
+ * @param h		header
+ * @return		referenced header instance
+ */
+Header headerLink(Header h)	/*@modifies h @*/;
 
-Header headerNew(void);
+/** \ingroup header
+ * Dereference a header instance.
+ * @param h		header
+ */
 void headerFree( /*@killref@*/ Header h);
 
-/* dump a header to a file, in human readable format */
+/** \ingroup header
+ * Return header reference count.
+ * @param h		header
+ * @return		no. of references
+ */
+int headerUsageCount(Header h)	/*@*/;
+
+/** \ingroup header
+ * Dump a header in human readable format (for debugging).
+ * @param h		header
+ * @param flags		0 or HEADER_DUMP_LINLINE
+ * @param tags		array of tag name/value pairs
+ */
 void headerDump(Header h, FILE *f, int flags,
 		const struct headerTagTableEntry * tags);
+#define HEADER_DUMP_INLINE   1
 
-/* the returned string must be free()d */
-char * headerSprintf(Header h, const char * fmt,
+typedef /*@observer@*/ const char * errmsg_t;
+
+/** \ingroup header
+ * Return formatted output string from header tags.
+ * The returned string must be free()d.
+ *
+ * @param h		header
+ * @param fmt		format to use
+ * @param tags		array of tag name/value pairs
+ * @param extentions	chained table of formatting extensions.
+ * @retval errmsg	error message (if any)
+ * @return		formatted output string (malloc'ed)
+ */
+/*@only@*/ char * headerSprintf(Header h, const char * fmt,
 		     const struct headerTagTableEntry * tags,
 		     const struct headerSprintfExtension * extentions,
-		     /*@out@*/ const char ** error);
+		     /*@out@*/ errmsg_t * errmsg)
+	/*@modifies h, *errmsg @*/;
+
+/** \ingroup header
+ * Add tag to header.
+ * Duplicate tags are okay, but only defined for iteration (with the
+ * exceptions noted below). While you are allowed to add i18n string
+ * arrays through this function, you probably don't mean to. See
+ * headerAddI18NString() instead.
+ *
+ * @param h		header
+ * @param tag		tag
+ * @param type		tag value data type
+ * @param p		pointer to tag value(s)
+ * @param c		number of values
+ * @return		1 on success, 0 on failure
+ */
+int headerAddEntry(Header h, int_32 tag, int_32 type, const void *p, int_32 c)
+	/*@modifies h @*/;
+
+/** \ingroup header
+ * Modify tag in header.
+ * If there are multiple entries with this tag, the first one gets replaced.
+ * @param h		header
+ * @param tag		tag
+ * @param type		tag value data type
+ * @param p		pointer to tag value(s)
+ * @param c		number of values
+ * @return		1 on success, 0 on failure
+ */
+int headerModifyEntry(Header h, int_32 tag, int_32 type, void *p, int_32 c)
+	/*@modifies h @*/;
 
-#define HEADER_DUMP_INLINE   1
+/** \ingroup header
+ * Return array of locales found in header.
+ * @param h		header
+ * @return		array of locales
+ */
+char ** headerGetLangs(Header h)
+	/*@modifies h @*/;
 
-/* Duplicate tags are okay, but only defined for iteration (with the
-   exceptions noted below). While you are allowed to add i18n string
-   arrays through this function, you probably don't mean to. See
-   headerAddI18NString() instead */
-int headerAddEntry(Header h, int_32 tag, int_32 type, const void *p, int_32 c);
-/* if there are multiple entries with this tag, the first one gets replaced */
-int headerModifyEntry(Header h, int_32 tag, int_32 type, void *p, int_32 c);
-
-/* Return array of lang names */
-char **headerGetLangs(Header h);
-
-/* A NULL lang is interpreted as the C locale.  Here are the rules:
-
-	1) If the tag isn't in the Header, it's added with the passed string
-	   as a version.
-	2) If the tag occurs multiple times in entry, which tag is affected
-	   by the operation is undefined.
-	2) If the tag is in the header w/ this language, the entry is
-	   *replaced* (like headerModifyEntry()).
-
-   This function is intended to just "do the right thing". If you need
-   more fine grained control use headerAddEntry() and headerModifyEntry()
-   but be careful!
-*/
+/** \ingroup header
+ * Add locale specific tag to header.
+ * A NULL lang is interpreted as the C locale.  Here are the rules:
+ *
+ *	1) If the tag isn't in the Header, it's added with the passed string
+ *	   as a version.
+ *	2) If the tag occurs multiple times in entry, which tag is affected
+ *	   by the operation is undefined.
+ *	2) If the tag is in the header w/ this language, the entry is
+ *	   *replaced* (like headerModifyEntry()).
+ *
+ * This function is intended to just "do the right thing". If you need
+ * more fine grained control use headerAddEntry() and headerModifyEntry().
+ *
+ * @param h		header
+ * @param tag		tag
+ * @param string	tag value
+ * @param lang		locale
+ * @return		1 on success, 0 on failure
+ */
 int headerAddI18NString(Header h, int_32 tag, const char * string,
-	const char * lang);
-
-/* Appends item p to entry w/ tag and type as passed. Won't work on
-   RPM_STRING_TYPE. Any pointers from headerGetEntry() for this entry
-   are invalid after this call has been made! */
-int headerAppendEntry(Header h, int_32 tag, int_32 type, void * p, int_32 c);
+	const char * lang)
+	/*@modifies h @*/;
+
+/** \ingroup header
+ * Append element to tag array in header.
+ * Appends item p to entry w/ tag and type as passed. Won't work on
+ * RPM_STRING_TYPE. Any pointers from headerGetEntry() for this entry
+ * are invalid after this call has been made!
+ *
+ * @param h		header
+ * @param tag		tag
+ * @param type		tag value data type
+ * @param p		pointer to tag value(s)
+ * @param c		number of values
+ * @return		1 on success, 0 on failure
+ */
+int headerAppendEntry(Header h, int_32 tag, int_32 type, void * p, int_32 c)
+	/*@modifies h @*/;
+
+/** \ingroup header
+ * Add or append element to tag array in header.
+ * @param h		header
+ * @param tag		tag
+ * @param type		tag value data type
+ * @param p		pointer to tag value(s)
+ * @param c		number of values
+ * @return		1 on success, 0 on failure
+ */
 int headerAddOrAppendEntry(Header h, int_32 tag, int_32 type,
-			   void * p, int_32 c);
-
-/* Will never return RPM_I18NSTRING_TYPE! RPM_STRING_TYPE elements w/
-   RPM_I18NSTRING_TYPE equivalent enreies are translated (if HEADER_I18NTABLE
-   entry is present). */
+			   void * p, int_32 c)
+		/*@modifies h @*/;
+
+/** \ingroup header
+ * Retrieve tag value.
+ * Will never return RPM_I18NSTRING_TYPE! RPM_STRING_TYPE elements with
+ * RPM_I18NSTRING_TYPE equivalent entries are translated (if HEADER_I18NTABLE
+ * entry is present).
+ *
+ * @param h		header
+ * @param tag		tag
+ * @retval type		address of tag value data type
+ * @retval p		address of pointer to tag value(s)
+ * @retval c		address of number of values
+ * @return		1 on success, 0 on failure
+ */
 int headerGetEntry(Header h, int_32 tag, /*@out@*/ int_32 *type,
-	/*@out@*/ void **p, /*@out@*/int_32 *c);
+	/*@out@*/ void **p, /*@out@*/int_32 *c)
+		/*@modifies h, *type, *p, *c @*/;
 
-/* This gets an entry, and uses as little extra RAM as possible to represent
-   it (this is only an issue for RPM_STRING_ARRAY_TYPE. */
+/** \ingroup header
+ * Retrieve tag value using header internal array.
+ * Get an entry using as little extra RAM as possible to return the tag value.
+ * This is only an issue for RPM_STRING_ARRAY_TYPE.
+ *
+ * @param h		header
+ * @param tag		tag
+ * @retval type		address of tag value data type
+ * @retval p		address of pointer to tag value(s)
+ * @retval c		address of number of values
+ * @return		1 on success, 0 on failure
+ */
 int headerGetEntryMinMemory(Header h, int_32 tag, int_32 *type,
-	/*@out@*/ void **p, /*@out@*/ int_32 *c);
+	/*@out@*/ void **p, /*@out@*/ int_32 *c)
+		/*@modifies h, *type, *p, *c @*/;
 
-/* If *type is RPM_NULL_TYPE any type will match, otherwise only *type will
-   match. */
+/** \ingroup header
+ * Retrieve tag value with type match.
+ * If *type is RPM_NULL_TYPE any type will match, otherwise only *type will
+ * match.
+ *
+ * @param h		header
+ * @param tag		tag
+ * @retval type		address of tag value data type
+ * @retval p		address of pointer to tag value(s)
+ * @retval c		address of number of values
+ * @return		1 on success, 0 on failure
+ */
 int headerGetRawEntry(Header h, int_32 tag, /*@out@*/ int_32 *type,
-	/*@out@*/ void **p, /*@out@*/ int_32 *c);
+	/*@out@*/ void **p, /*@out@*/ int_32 *c)
+		/*@modifies h, *type, *p, *c @*/;
+
+/** \ingroup header
+ * Check if tag is in header.
+ * @param h		header
+ * @return		1 on success, 0 on failure
+ */
+int headerIsEntry(Header h, int_32 tag)
+	/*@modifies h @*/;
 
-int headerIsEntry(Header h, int_32 tag);
-/* removes all entries of type tag from the header, returns 1 if none were
-   found */
-int headerRemoveEntry(Header h, int_32 tag);
+/** \ingroup header
+ * Delete tag in header.
+ * Removes all entries of type tag from the header, returns 1 if none were
+ * found.
+ *
+ * @param h		header
+ * @return		0 on success, 1 on failure (INCONSISTENT)
+ */
+int headerRemoveEntry(Header h, int_32 tag)
+	/*@modifies h @*/;
 
-HeaderIterator headerInitIterator(Header h);
+/** \ingroup header
+ * Create header tag iterator.
+ * @param h		header
+ * @return		header tag iterator
+ */
+HeaderIterator headerInitIterator(Header h)
+	/*@modifies h @*/;
+
+/** \ingroup header
+ * Return next tag from header.
+ * @param iter		header tag iterator
+ * @retval tag		address of tag
+ * @retval type		address of tag value data type
+ * @retval p		address of pointer to tag value(s)
+ * @retval c		address of number of values
+ * @return		1 on success, 0 on failure
+ */
 int headerNextIterator(HeaderIterator iter,
 	/*@out@*/ int_32 *tag, /*@out@*/ int_32 *type, /*@out@*/ void **p,
-	/*@out@*/ int_32 *c);
+	/*@out@*/ int_32 *c)
+		/*@modifies iter, *tag, *type, *p, *c @*/;
+
+/** \ingroup header
+ * Destroy header tag iterator.
+ * @param iter		header tag iterator
+ */
 void headerFreeIterator( /*@only@*/ HeaderIterator iter);
 
-Header headerCopy(Header h);
-void headerSort(Header h);
-Header headerLink(Header h);
-int headerUsageCount(Header h);
+/** \ingroup header
+ * Duplicate a header.
+ * @param h		header
+ * @return		new header instance
+ */
+Header headerCopy(Header h)
+	/*@modifies h @*/;
 
-void headerCopyTags(Header headerFrom, Header headerTo, int_32 *tagstocopy);
+/** \ingroup header
+ * Sort tags in header.
+ * @param h		header
+ */
+void headerSort(Header h)
+	/*@modifies h @*/;
+
+/** \ingroup header
+ * Duplicate tag values from one header into another.
+ * @param headerFrom		source header
+ * @param headerTo		destination header
+ * @param tagstocopy		array of tags that are copied
+ */
+void headerCopyTags(Header headerFrom, Header headerTo, int_32 *tagstocopy)
+	/*@modifies headerFrom, headerTo @*/;
 
 /* Entry Types */
 
diff --git a/lib/install.c b/lib/install.c
index 2b8092e79..499b55d1b 100644
--- a/lib/install.c
+++ b/lib/install.c
@@ -1,3 +1,7 @@
+/** \ingroup rpmtrans payload
+ * \file lib/install.c
+ */
+
 #include "system.h"
 
 #include <rpmlib.h>
diff --git a/lib/install.h b/lib/install.h
index 33d3132d3..b3f61b925 100644
--- a/lib/install.h
+++ b/lib/install.h
@@ -1,6 +1,10 @@
 #ifndef H_INSTALL
 #define H_INSTALL
 
+/** \file lib/install.h
+ *
+ */
+
 #include <rpmlib.h>
 
 /**
diff --git a/lib/md5.c b/lib/md5.c
index 27d2a5499..92f1ff23d 100644
--- a/lib/md5.c
+++ b/lib/md5.c
@@ -1,4 +1,5 @@
-/*
+/** \ingroup signature
+ * \file lib/md5.c
  * This code implements the MD5 message-digest algorithm.
  * The algorithm is due to Ron Rivest.  This code was
  * written by Colin Plumb in 1993, no copyright is claimed.
diff --git a/lib/md5.h b/lib/md5.h
index 45c28a233..8ef18ea4b 100644
--- a/lib/md5.h
+++ b/lib/md5.h
@@ -1,6 +1,10 @@
 #ifndef MD5_H
 #define MD5_H
 
+/** \file lib/md5.h
+ *
+ */
+
 #include <sys/types.h>
 
 typedef unsigned int uint32;
diff --git a/lib/md5sum.c b/lib/md5sum.c
index bdd1e0636..ddddf9612 100644
--- a/lib/md5sum.c
+++ b/lib/md5sum.c
@@ -1,6 +1,6 @@
-/*
- * md5sum.c	- Generate/check MD5 Message Digests
- *
+/** \ingroup signature.c
+ * \file lib/md5sum.c
+ * Generate/check MD5 Message Digests.
  * Compile and link with md5.c.  If you don't have getopt() in your library
  * also include getopt.c.  For MSDOS you can also link with the wildcard
  * initialization function (wildargs.obj for Turbo C and setargv.obj for MSC)
diff --git a/lib/misc.c b/lib/misc.c
index 040b279d5..759424853 100644
--- a/lib/misc.c
+++ b/lib/misc.c
@@ -1,3 +1,7 @@
+/**
+ * \file lib/misc.c
+ */
+
 #include "system.h"
 
 static int _debug = 0;
diff --git a/lib/misc.h b/lib/misc.h
index dda1035bc..56f60b4f7 100644
--- a/lib/misc.h
+++ b/lib/misc.h
@@ -1,6 +1,10 @@
 #ifndef H_MISC
 #define H_MISC
 
+/** \file lib/misc.h
+ *
+ */
+
 #include <unistd.h>
 #include <sys/types.h>
 
diff --git a/lib/oldrpmdb.h b/lib/oldrpmdb.h
index ea08209af..cce86cb0e 100644
--- a/lib/oldrpmdb.h
+++ b/lib/oldrpmdb.h
@@ -1,6 +1,10 @@
 #ifndef _H_OLDRPMDB
 #define _H_OLDRPMDB
 
+/** \file lib/oldrpmdb.h
+ *
+ */
+
 #include <gdbm.h>
 
 #include <oldheader.h>
diff --git a/lib/package.c b/lib/package.c
index ec2ba8022..e4702df28 100644
--- a/lib/package.c
+++ b/lib/package.c
@@ -1,3 +1,7 @@
+/** \ingroup header
+ * \file lib/package.c
+ */
+
 #include "system.h"
 
 #ifdef	__LCLINT__
diff --git a/lib/poptBT.c b/lib/poptBT.c
index fa69b9dc6..d77913b79 100644
--- a/lib/poptBT.c
+++ b/lib/poptBT.c
@@ -1,4 +1,5 @@
-/** \file poptBT.c
+/**
+ * \file lib/poptBT.c
  *  Popt tables for build modes.
  */
 
diff --git a/lib/poptQV.c b/lib/poptQV.c
index d8e123bf0..595829afd 100644
--- a/lib/poptQV.c
+++ b/lib/poptQV.c
@@ -1,3 +1,7 @@
+/**
+ * \file lib/poptQV.c
+ *  Popt tables for query/verify modes.
+ */
 #include "system.h"
 
 #include "rpmbuild.h"
diff --git a/lib/problems.c b/lib/problems.c
index 55ad5b2aa..aeef3297b 100644
--- a/lib/problems.c
+++ b/lib/problems.c
@@ -1,3 +1,7 @@
+/**
+ * \file lib/problems.c
+ */
+
 #include "system.h"
 
 #include <rpmlib.h>
diff --git a/lib/query.c b/lib/query.c
index 46ef87775..5eef30e3d 100644
--- a/lib/query.c
+++ b/lib/query.c
@@ -1,3 +1,7 @@
+/** \ingroup rpmcli
+ * \file lib/query.c
+ */
+
 #include "system.h"
 
 #ifndef PATH_MAX
diff --git a/lib/rpmchecksig.c b/lib/rpmchecksig.c
index fc318b2fe..5743b385a 100644
--- a/lib/rpmchecksig.c
+++ b/lib/rpmchecksig.c
@@ -1,4 +1,7 @@
-/* checksig.c: verify the signature of an RPM */
+/** \ingroup rpmcli
+ * \file lib/rpmchecksig.c
+ * Verify the signature of a package.
+ */
 
 #include "system.h"
 
diff --git a/lib/rpmdb.c b/lib/rpmdb.c
index 72df79857..506dff5b5 100644
--- a/lib/rpmdb.c
+++ b/lib/rpmdb.c
@@ -1,3 +1,7 @@
+/** \ingroup rpmdb dbi
+ * \file lib/rpmdb.c
+ */
+
 #include "system.h"
 
 static int _debug = 0;
diff --git a/lib/rpmdb.h b/lib/rpmdb.h
index 5426b3e3a..f687d40b3 100644
--- a/lib/rpmdb.h
+++ b/lib/rpmdb.h
@@ -1,7 +1,8 @@
 #ifndef H_RPMDB
 #define H_RPMDB
 
-/** \file lib/rpmdb.h
+/** \ingroup rpmdb dbi db1 db3
+ * \file lib/rpmdb.h
  * Access RPM indices using Berkeley db[123] interface.
  */
 
@@ -13,7 +14,7 @@ typedef /*@abstract@*/ struct _dbiIndexItem * dbiIndexItem;
 typedef /*@abstract@*/ struct _dbiIndex * dbiIndex;
 
 /* this will break if sizeof(int) != 4 */
-/**
+/** \ingroup dbi
  * A single item from an index database (i.e. the "data returned").
  * Note: In rpm-3.0.4 and earlier, this structure was passed by value,
  * and was identical to the "data saved" structure below.
@@ -25,7 +26,7 @@ struct _dbiIndexItem {
     unsigned int dbNum;			/*!< database index */
 };
 
-/**
+/** \ingroup dbi
  * A single item in an index database (i.e. the "data saved").
  */
 struct _dbiIR {
@@ -34,7 +35,7 @@ struct _dbiIR {
 };
 typedef	struct _dbiIR * DBIR_t;
 
-/**
+/** \ingroup dbi
  * Items retrieved from the index database.
  */
 struct _dbiIndexSet {
@@ -50,7 +51,7 @@ struct _dbiIndexSet {
 #define	DB_LSN	void
 #endif
 
-/**
+/** \ingroup dbi
  * Private methods for accessing an index database.
  */
 struct _dbiVec {
@@ -58,7 +59,7 @@ struct _dbiVec {
     int dbv_minor;			/*!< Berkeley db version minor */
     int dbv_patch;			/*!< Berkeley db version patch */
 
-/**
+/** \ingroup dbi
  * Return handle for an index database.
  * @param rpmdb		rpm database
  * @param rpmtag	rpm tag
@@ -66,7 +67,7 @@ struct _dbiVec {
  */
     int (*open) (rpmdb rpmdb, int rpmtag, /*@out@*/ dbiIndex * dbip);
 
-/**
+/** \ingroup dbi
  * Close index database.
  * @param dbi		index database handle
  * @param flags		(unused)
@@ -74,7 +75,7 @@ struct _dbiVec {
  */
     int (*close) (/*@only@*/ dbiIndex dbi, unsigned int flags);
 
-/**
+/** \ingroup dbi
  * Flush pending operations to disk.
  * @param dbi		index database handle
  * @param flags		(unused)
@@ -82,7 +83,7 @@ struct _dbiVec {
  */
     int (*sync) (dbiIndex dbi, unsigned int flags);
 
-/**
+/** \ingroup dbi
  * Open database cursor.
  * @param dbi		index database handle
  * @param dbcp		address of database cursor
@@ -90,7 +91,7 @@ struct _dbiVec {
  */
     int (*copen) (dbiIndex dbi, /*@out@*/ DBC ** dbcp, unsigned int flags);
 
-/**
+/** \ingroup dbi
  * Close database cursor.
  * @param dbi		index database handle
  * @param dbcursor	database cursor
@@ -98,7 +99,7 @@ struct _dbiVec {
  */
     int (*cclose) (dbiIndex dbi, /*@only@*/ DBC * dbcursor, unsigned int flags);
 
-/**
+/** \ingroup dbi
  * Delete (key,data) pair(s) using db->del or dbcursor->c_del.
  * @param dbi		index database handle
  * @param dbcursor	database cursor
@@ -109,7 +110,7 @@ struct _dbiVec {
  */
     int (*cdel) (dbiIndex dbi, DBC * dbcursor, const void * keyp, size_t keylen, unsigned int flags);
 
-/**
+/** \ingroup dbi
  * Retrieve (key,data) pair using db->get or dbcursor->c_get.
  * @param dbi		index database handle
  * @param dbcursor	database cursor
@@ -125,7 +126,7 @@ struct _dbiVec {
 			/*@out@*/ void ** datapp, /*@out@*/ size_t * datalenp,
 			unsigned int flags);
 
-/**
+/** \ingroup dbi
  * Store (key,data) pair using db->put or dbcursor->c_put.
  * @param dbi		index database handle
  * @param dbcursor	database cursor
@@ -141,7 +142,7 @@ struct _dbiVec {
 			const void * datap, size_t datalen,
 			unsigned int flags);
 
-/**
+/** \ingroup dbi
  * Is database byte swapped?
  * @param dbi		index database handle
  * @return		0 no
@@ -150,7 +151,7 @@ struct _dbiVec {
 
 };
 
-/**
+/** \ingroup dbi
  * Describes an index database (implemented on Berkeley db[123] API).
  */
 struct _dbiIndex {
@@ -242,7 +243,7 @@ struct _dbiIndex {
 
 };
 
-/**
+/** \ingroup rpmdb
  * Describes the collection of index databases used by rpm.
  */
 struct rpmdb_s {
@@ -278,19 +279,19 @@ struct rpmdb_s {
 extern "C" {
 #endif
 
-/**
+/** \ingroup db3
  * Return new configured index database handle instance.
  * @param rpmdb		rpm database
  */
 /*@only@*/ /*@null@*/ dbiIndex db3New(/*@keep@*/ rpmdb rpmdb, int rpmtag);
 
-/**
+/** \ingroup db3
  * Destroy index database handle instance.
  * @param dbi		index database handle
  */
 void db3Free( /*@only@*/ /*@null@*/ dbiIndex dbi);
 
-/**
+/** \ingroup dbi
  * Return handle for an index database.
  * @param rpmdb		rpm database
  * @param rpmtag	rpm tag
@@ -300,7 +301,7 @@ void db3Free( /*@only@*/ /*@null@*/ dbiIndex dbi);
 /*@only@*/ /*@null@*/ dbiIndex dbiOpen(rpmdb rpmdb, int rpmtag,
 		unsigned int flags);
 
-/**
+/** \ingroup dbi
  * @param dbi		index database handle
  * @param flags		(unused)
  */
@@ -309,7 +310,7 @@ int XdbiCopen(dbiIndex dbi, /*@out@*/ DBC ** dbcp, unsigned int flags, const cha
 #define	dbiCopen(_a,_b,_c) \
 	XdbiCopen(_a, _b, _c, __FILE__, __LINE__)
 
-/**
+/** \ingroup dbi
  * @param dbi		index database handle
  * @param flags		(unused)
  */
@@ -318,7 +319,7 @@ int XdbiCclose(dbiIndex dbi, /*@only@*/ DBC * dbcursor, unsigned int flags, cons
 #define	dbiCclose(_a,_b,_c) \
 	XdbiCclose(_a, _b, _c, __FILE__, __LINE__)
 
-/**
+/** \ingroup dbi
  * Delete (key,data) pair(s) from index database.
  * @param dbi		index database handle
  * @param keyp		key data
@@ -329,7 +330,7 @@ int XdbiCclose(dbiIndex dbi, /*@only@*/ DBC * dbcursor, unsigned int flags, cons
 int dbiDel(dbiIndex dbi, DBC * dbcursor, const void * keyp, size_t keylen,
 	unsigned int flags);
 
-/**
+/** \ingroup dbi
  * Retrieve (key,data) pair from index database.
  * @param dbi		index database handle
  * @param keypp		address of key data
@@ -342,7 +343,7 @@ int dbiDel(dbiIndex dbi, DBC * dbcursor, const void * keyp, size_t keylen,
 int dbiGet(dbiIndex dbi, DBC * dbcursor, void ** keypp, size_t * keylenp,
         void ** datapp, size_t * datalenp, unsigned int flags);
 
-/**
+/** \ingroup dbi
  * Store (key,data) pair in index database.
  * @param dbi		index database handle
  * @param keyp		key data
@@ -355,7 +356,7 @@ int dbiGet(dbiIndex dbi, DBC * dbcursor, void ** keypp, size_t * keylenp,
 int dbiPut(dbiIndex dbi, DBC * dbcursor, const void * keyp, size_t keylen,
 	const void * datap, size_t datalen, unsigned int flags);
 
-/**
+/** \ingroup dbi
  * Close index database.
  * @param dbi		index database handle
  * @param flags		(unused)
@@ -363,7 +364,7 @@ int dbiPut(dbiIndex dbi, DBC * dbcursor, const void * keyp, size_t keylen,
  */
 int dbiClose(/*@only@*/ dbiIndex dbi, unsigned int flags);
 
-/**
+/** \ingroup dbi
  * Flush pending operations to disk.
  * @param dbi		index database handle
  * @param flags		(unused)
@@ -371,44 +372,44 @@ int dbiClose(/*@only@*/ dbiIndex dbi, unsigned int flags);
  */
 int dbiSync (dbiIndex dbi, unsigned int flags);
 
-/**
+/** \ingroup dbi
  * Is database byte swapped?
  * @param dbi		index database handle
  * @return		0 no
  */
 int dbiByteSwapped(dbiIndex dbi);
 
-/**
- * Return base file name for index database (legacy).
+/** \ingroup db1
+ * Return base file name for db1 database (legacy).
  * @param rpmtag	rpm tag
- * @return		base file name
+ * @return		base file name of db1 database
  */
 char * db1basename(int rpmtag);
 
-/**
+/** \ingroup rpmdb
  */
 unsigned int rpmdbGetIteratorFileNum(rpmdbMatchIterator mi);
 
-/**
+/** \ingroup rpmdb
  * @param rpmdb		rpm database
  */
 int rpmdbFindFpList(rpmdb rpmdb, fingerPrint * fpList, /*@out@*/dbiIndexSet * matchList, 
 		    int numItems);
 
-/**
+/** \ingroup dbi
  * Destroy set of index database items.
  * @param set	set of index database items
  */
 void dbiFreeIndexSet(/*@only@*/ /*@null@*/ dbiIndexSet set);
 
-/**
+/** \ingroup dbi
  * Count items in index database set.
  * @param set	set of index database items
  * @return	number of items
  */
 unsigned int dbiIndexSetCount(dbiIndexSet set);
 
-/**
+/** \ingroup dbi
  * Return record offset of header from element in index database set.
  * @param set	set of index database items
  * @param recno	index of item in set
@@ -416,7 +417,7 @@ unsigned int dbiIndexSetCount(dbiIndexSet set);
  */
 unsigned int dbiIndexRecordOffset(dbiIndexSet set, int recno);
 
-/**
+/** \ingroup dbi
  * Return file index from element in index database set.
  * @param set	set of index database items
  * @param recno	index of item in set
diff --git a/lib/rpminstall.c b/lib/rpminstall.c
index a63789dda..1ed538c6e 100644
--- a/lib/rpminstall.c
+++ b/lib/rpminstall.c
@@ -1,3 +1,7 @@
+/** \ingroup rpmcli
+ * \file lib/rpminstall.c
+ */
+
 #include "system.h"
 
 #include <rpmlib.h>
diff --git a/lib/rpmlead.c b/lib/rpmlead.c
index 9ec3f6d75..e80f9d4ba 100644
--- a/lib/rpmlead.c
+++ b/lib/rpmlead.c
@@ -1,3 +1,7 @@
+/** \ingroup lead
+ * \file lib/rpmlead.c
+ */
+
 #include "system.h"
 
 #if HAVE_MACHINE_TYPES_H
diff --git a/lib/rpmlead.h b/lib/rpmlead.h
index a87fefe38..bc417277d 100644
--- a/lib/rpmlead.h
+++ b/lib/rpmlead.h
@@ -1,6 +1,10 @@
 #ifndef _H_RPMLEAD
 #define _H_RPMLEAD
 
+/** \file lib/rpmlead.h
+ *
+ */
+
 #include <rpmlib.h>
 
 /* Other definitions went to rpmlib.h */
diff --git a/lib/rpmlib.h b/lib/rpmlib.h
index 61d5df7a2..6be2e7c0a 100644
--- a/lib/rpmlib.h
+++ b/lib/rpmlib.h
@@ -1,6 +1,11 @@
 #ifndef H_RPMLIB
 #define	H_RPMLIB
 
+/** \file lib/rpmlib.h
+ * \ingroup rpmcli rpmrc rpmdep rpmtrans rpmdb lead signature header payload dbi
+ *
+ */
+
 /* This is the *only* module users of rpmlib should need to include */
 
 /* and it shouldn't need these :-( */
@@ -11,8 +16,6 @@
 #include "header.h"
 #include "popt.h"
 
-typedef /*@abstract@*/ struct _dbiIndexSet * dbiIndexSet;
-
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -52,22 +55,32 @@ int headerNVR(Header h, /*@out@*/ const char **np, /*@out@*/ const char **vp,
 	/*@out@*/ const char **rp) /*@modifies *np, *vp, *rp @*/;
 
 /**
+ * Retrieve file names from header.
+ * The representation of file names in package headers changed in rpm-4.0.
+ * Originally, file names were stored as an array of paths. In rpm-4.0,
+ * file names are stored as separate arrays of dirname's and basename's,
+ * with a dirname index to associate the correct dirname with each basname.
+ * This function is used to retrieve file names independent of how the
+ * file names are represented in the package header.
+ * 
  * @param h		header
+ * @retval fileListPtr	address of array of file names
+ * @retval fileCountPtr	address of number of files
  */
-void rpmBuildFileList(Header h,/*@out@*/ const char *** fileListPtr, 
+void rpmBuildFileList(Header h, /*@out@*/ const char *** fileListPtr, 
 	/*@out@*/ int * fileCountPtr)
 		/*@modifies *fileListPtr, *fileCountPtr @*/;
 
 /**
  * Retrieve tag info from header.
- * XXX This is a "dressed" entry to headerGetEntry to do:
+ * This is a "dressed" entry to headerGetEntry to do:
  *	1) DIRNAME/BASENAME/DIRINDICES -> FILENAMES tag conversions.
  *	2) i18n lookaside (if enabled).
  *
  * @param h		header
  * @param tag		tag
  * @retval type		address of tag value data type
- * @retval p		address of pointer to tag value
+ * @retval p		address of pointer to tag value(s)
  * @retval c		address of number of values
  * @return		0 on success, 1 on bad magic, 2 on error
  */
@@ -77,13 +90,14 @@ int rpmHeaderGetEntry(Header h, int_32 tag, /*@out@*/ int_32 *type,
 
 /**
  * Retrieve tag info from header.
- * XXX Yet Another dressed entry to unify signature/header tag retrieval.
+ * Yet Another "dressed" entry to headerGetEntry in order to unify
+ * signature/header tag retrieval.
  * @param leadp		rpm lead
  * @param h		header
  * @param sigs		signatures
  * @param tag		tag
  * @retval type		address of tag value data type
- * @retval p		address of pointer to tag value
+ * @retval p		address of pointer to tag value(s)
  * @retval c		address of number of values
  * @return		0 on success, 1 on bad magic, 2 on error
  */
@@ -91,13 +105,20 @@ int rpmPackageGetEntry(void *leadp, Header sigs, Header h,
         int_32 tag, int_32 *type, void **p, int_32 *c)
 		/*@modifies *type, *p, *c @*/;
 
-/** */
+/**
+ * Automatically generated table of tag name/value pairs.
+ */
 extern const struct headerTagTableEntry rpmTagTable[];
-/** */
+
+/**
+ * Number of entries in rpmTagTable.
+ */
 extern const int rpmTagTableSize;
 
-/* this chains to headerDefaultFormats[] */
-/** */
+/**
+ * Table of query format extensions.
+ * @note Chains to headerDefaultFormats[].
+ */
 extern const struct headerSprintfExtension rpmHeaderFormats[];
 
 /* these pseudo-tags are used by the dbi iterator interface */
@@ -310,6 +331,11 @@ extern const struct headerSprintfExtension rpmHeaderFormats[];
 
 #define	isDependsMULTILIB(_dflags)	((_dflags) & RPMSENSE_MULTILIB)
 
+#define	xfree(_p)	free((void *)_p)
+
+/* ==================================================================== */
+/** \name RPMRC */
+/*@{*/
 /* Stuff for maintaining "variables" like SOURCEDIR, BUILDDIR, etc */
 
 /* #define	RPMVAR_SOURCEDIR		0 -- No longer used */
@@ -369,109 +395,152 @@ extern const struct headerSprintfExtension rpmHeaderFormats[];
 
 #define	RPMVAR_NUM			55	/* number of RPMVAR entries */
 
-#define	xfree(_p)	free((void *)_p)
-
-/** rpmrc.c **/
-
-/**
+/** \ingroup rpmrc
+ * Return value of rpmrc variable.
+ * @deprecated Use rpmExpand() with appropriate macro expression.
  */
 const char * rpmGetVar(int var);
 
-/**
+/** \ingroup rpmrc
+ * Set value of rpmrc variable.
+ * @deprecated Use rpmDefineMacro() to change appropriate macro instead.
  */
 void rpmSetVar(int var, const char *val);
 
+/** \ingroup rpmrc
+ * Build and install arch/os table identifiers.
+ */
 #define	RPM_MACHTABLE_INSTARCH		0
 #define	RPM_MACHTABLE_INSTOS		1
 #define	RPM_MACHTABLE_BUILDARCH		2
 #define	RPM_MACHTABLE_BUILDOS  		3
 #define	RPM_MACHTABLE_COUNT		4	/* number of arch/os tables */
 
-/**
+/** \ingroup rpmrc
+ * Read rpmrc (and macro) configuration file(s) for a target.
+ * @param file		colon separated files to read (NULL uses default)
+ * @param target	target platform (NULL uses default)
+ * @return		0 on success, -1 on error
  */
 int rpmReadConfigFiles(const char * file, const char * target);
 
-/**
+/** \ingroup rpmrc
+ * Read rpmrc (and macro) configuration file(s).
+ * @param file		colon separated files to read (NULL uses default)
+ * @return		0 on succes
  */
 int rpmReadRC(const char * file);
 
-/**
+/** \ingroup rpmrc
+ * Return current arch name and/or number.
+ * @retval name		address of arch name (or NULL)
+ * @retval num		address of arch number (or NULL)
  */
 void rpmGetArchInfo( /*@out@*/ const char ** name, /*@out@*/ int * num);
 
-/**
+/** \ingroup rpmrc
+ * Return current os name and/or number.
+ * @retval name		address of os name (or NULL)
+ * @retval num		address of os number (or NULL)
  */
 void rpmGetOsInfo( /*@out@*/ const char ** name, /*@out@*/ int * num);
 
-/**
+/** \ingroup rpmrc
+ * Return arch/os score of a name.
+ * An arch score measures the nearness of an arch name to the currently
+ * running (or defined) platform arch. For example, the score of "i586"
+ * on an i686 platform is (usually) 1. The arch score is used to select
+ * one of several otherwise identical packages based on the arch/os hints
+ * in the header of the intended platform.
+ *
+ * @param type		any of the RPM_MACHTABLE_* constants
+ * @param name		name
+ * @return		arch score
  */
 int rpmMachineScore(int type, const char * name);
 
-/**
+/** \ingroup rpmrc
+ * Display current rpmrc (and macro) configuration.
+ * @param f		output file handle
+ * @return		0 always
  */
 int rpmShowRC(FILE *f);
 
-/**
+/** \ingroup rpmrc
+ * @param archTable
+ * @param osTable
  */
 void rpmSetTables(int archTable, int osTable);  /* only used by build code */
 
-/* if either are NULL, they are set to the default value (munged uname())
-   pushed through a translation table (if appropriate) */
-/**
+/** \ingroup rpmrc
+ * Set current arch/os names.
+ * NULL as argument is set to the default value (munged uname())
+ * pushed through a translation table (if appropriate).
+ *
+ * @param arch		arch name (or NULL)
+ * @param os		os name (or NULL)
  */
 void rpmSetMachine(const char * arch, const char * os);
 
-/**
+/** \ingroup rpmrc
+ * Return current arch/os names.
+ * @retval arch		address of arch name (or NULL)
+ * @retval os		address of os name (or NULL)
  */
 void rpmGetMachine( /*@out@*/ const char **arch, /*@out@*/ const char **os);
 
-/**
+/** \ingroup rpmrc
+ * Destroy rpmrc arch/os compatibility tables.
  */
 void rpmFreeRpmrc(void);
 
+/*@}*/
 /* ==================================================================== */
-/** **/
+/** \name RPMDB */
+/*@{*/
 typedef /*@abstract@*/ struct rpmdb_s * rpmdb;
+typedef /*@abstract@*/ struct _dbiIndexSet * dbiIndexSet;
 
-/**
+/** \ingroup rpmdb
+ * Open rpm database.
  * @param root		path to top of install tree
  * @retval dbp		address of rpm database
- * @return
+ * @param mode		open(2) flags:  O_RDWR or O_RDONLY (O_CREAT also)
+ * @param perms		database permissions
+ * @return		0 on success
  */
 int rpmdbOpen (const char * root, /*@out@*/ rpmdb * dbp, int mode, int perms);
-    /* 0 on error */
 
-/**
+/** \ingroup rpmdb
  * Initialize database.
  * @param root		path to top of install tree
  * @param perms		database permissions
- * @return
+ * @return		0 on success
  */
 int rpmdbInit(const char * root, int perms);
-    /* nonzero on error */
 
-/**
+/** \ingroup rpmdb
  * Close all database indices and free rpmdb.
  * @param rpmdb		rpm database
  * @return		0 always
  */
 int rpmdbClose ( /*@only@*/ rpmdb rpmdb);
 
-/**
+/** \ingroup rpmdb
  * Sync all database indices.
  * @param rpmdb		rpm database
  * @return		0 always
  */
 int rpmdbSync (rpmdb rpmdb);
 
-/**
+/** \ingroup rpmdb
  * Open all database indices.
  * @param rpmdb		rpm database
  * @return		0 always
  */
 int rpmdbOpenAll (rpmdb rpmdb);
 
-/**
+/** \ingroup rpmdb
  * Return number of instances of package in rpm database.
  * @param db		rpm database
  * @param name		rpm package name
@@ -479,38 +548,38 @@ int rpmdbOpenAll (rpmdb rpmdb);
  */
 int rpmdbCountPackages(rpmdb db, const char *name);
 
-/**
+/** \ingroup rpmdb
  */
 typedef /*@abstract@*/ struct _rpmdbMatchIterator * rpmdbMatchIterator;
 
-/**
+/** \ingroup rpmdb
  * Destroy rpm database iterator.
  * @param mi		rpm database iterator
  */
 void rpmdbFreeIterator( /*@only@*/ rpmdbMatchIterator mi);
 
-/**
+/** \ingroup rpmdb
  * Return rpm database used by iterator.
  * @param mi		rpm database iterator
  * @return		rpm database handle
  */
 rpmdb rpmdbGetIteratorRpmDB(rpmdbMatchIterator mi);
 
-/**
+/** \ingroup rpmdb
  * Return join key for current position of rpm database iterator.
  * @param mi		rpm database iterator
  * @return		current join key
  */
 unsigned int rpmdbGetIteratorOffset(rpmdbMatchIterator mi);
 
-/**
+/** \ingroup rpmdb
  * Return number of elements in rpm database iterator.
  * @param mi		rpm database iterator
  * @return		number of elements
  */
 int rpmdbGetIteratorCount(rpmdbMatchIterator mi);
 
-/**
+/** \ingroup rpmdb
  * Append items to set of package instances to iterate.
  * @param mi		rpm database iterator
  * @param hdrNums	array of package instances
@@ -519,7 +588,7 @@ int rpmdbGetIteratorCount(rpmdbMatchIterator mi);
  */
 int rpmdbAppendIterator(rpmdbMatchIterator mi, int * hdrNums, int nHdrNums);
 
-/**
+/** \ingroup rpmdb
  * Remove items from set of package instances to iterate.
  * @param mi		rpm database iterator
  * @param hdrNums	array of package instances
@@ -530,42 +599,41 @@ int rpmdbAppendIterator(rpmdbMatchIterator mi, int * hdrNums, int nHdrNums);
 int rpmdbPruneIterator(rpmdbMatchIterator mi, int * hdrNums,
 	int nHdrNums, int sorted);
 
-/**
+/** \ingroup rpmdb
  * Modify iterator to filter out headers that do not match version.
- *  TODO: replace with a more general mechanism.
+ * @todo replace with a more general mechanism using RE's on tag content.
  * @param mi		rpm database iterator
  * @param version	version to check for
  */
 void rpmdbSetIteratorVersion(rpmdbMatchIterator mi, /*@kept@*/ const char * version);
 
-/**
+/** \ingroup rpmdb
  * Modify iterator to filter out headers that do not match release.
- *  TODO: replace with a more general mechanism.
+ * @todo replace with a more general mechanism using RE's on tag content.
  * @param mi		rpm database iterator
  * @param release	release to check for
  */
 void rpmdbSetIteratorRelease(rpmdbMatchIterator mi, /*@kept@*/ const char * release);
 
-/**
+/** \ingroup rpmdb
  * Modify iterator to mark header for lazy write.
- *  TODO: replace with a more general mechanism.
  * @param mi		rpm database iterator
  * @param modified	new value of modified
  * @return		previous value
  */
 int rpmdbSetIteratorModified(rpmdbMatchIterator mi, int modified);
 
-/**
+/** \ingroup rpmdb
  * Return next package header from iteration.
  * @param mi		rpm database iterator
  * @return		NULL on end of iteration.
  */
 Header rpmdbNextIterator(rpmdbMatchIterator mi);
-Header XrpmdbNextIterator(rpmdbMatchIterator mi, const char * f, unsigned int l);
 #define	rpmdbNextIterator(_a) \
 	XrpmdbNextIterator(_a, __FILE__, __LINE__)
+Header XrpmdbNextIterator(rpmdbMatchIterator mi, const char * f, unsigned int l);
 
-/**
+/** \ingroup rpmdb
  * Return database iterator.
  * @param rpmdb		rpm database
  * @param rpmtag	rpm tag
@@ -577,7 +645,7 @@ Header XrpmdbNextIterator(rpmdbMatchIterator mi, const char * f, unsigned int l)
 			/*@kept@*/ rpmdb rpmdb, int rpmtag,
 			const void * key, size_t keylen);
 
-/**
+/** \ingroup rpmdb
  * Remove package header from rpm database and indices.
  * @param rpmdb		rpm database
  * @param offset	location in Packages dbi
@@ -585,7 +653,7 @@ Header XrpmdbNextIterator(rpmdbMatchIterator mi, const char * f, unsigned int l)
  */
 int rpmdbRemove(rpmdb db, unsigned int offset);
 
-/**
+/** \ingroup rpmdb
  * Add package header to rpm database and indices.
  * @param rpmdb		rpm database
  * @param rpmtag	rpm tag
@@ -593,17 +661,96 @@ int rpmdbRemove(rpmdb db, unsigned int offset);
  */
 int rpmdbAdd(rpmdb rpmdb, Header dbentry);
 
-/**
+/** \ingroup rpmdb
+ * Rebuild database indices from package headers.
  * @param root		path to top of install tree
  */
 int rpmdbRebuild(const char * root);
 
+/*@}*/
+/* ==================================================================== */
+/** \name RPMPROBS */
+/*@{*/
+
+/** */
+typedef enum rpmProblemType_e { RPMPROB_BADARCH, 
+				RPMPROB_BADOS,
+				RPMPROB_PKG_INSTALLED,
+				RPMPROB_BADRELOCATE,
+				RPMPROB_REQUIRES,
+				RPMPROB_CONFLICT,
+				RPMPROB_NEW_FILE_CONFLICT,
+				RPMPROB_FILE_CONFLICT,
+				RPMPROB_OLDPACKAGE,
+				RPMPROB_DISKSPACE,
+				RPMPROB_BADPRETRANS
+ 			      } rpmProblemType;
+
+/** */
+typedef /*@abstract@*/ struct rpmProblem_s {
+    Header h, altH;
+/*@dependent@*/ const void * key;
+    rpmProblemType type;
+    int ignoreProblem;
+/*@only@*/ const char * str1;
+    unsigned long ulong1;
+} rpmProblem;
+
+/** */
+typedef /*@abstract@*/ struct rpmProblemSet_s {
+    int numProblems;
+    int numProblemsAlloced;
+    rpmProblem * probs;
+} * rpmProblemSet;
+
+/**
+ */
+void printDepFlags(FILE *fp, const char *version, int flags)
+	/*@modifies *fp @*/;
+
+/**
+ */
+struct rpmDependencyConflict {
+    char * byName, * byVersion, * byRelease;
+    Header byHeader;
+    /* these needs fields are misnamed -- they are used for the package
+       which isn't needed as well */
+    char * needsName, * needsVersion;
+    int needsFlags;
+    /*@observer@*/ /*@null@*/ const void * suggestedPackage; /* NULL if none */
+    enum { RPMDEP_SENSE_REQUIRES, RPMDEP_SENSE_CONFLICTS } sense;
+} ;
+
+/**
+ */
+void printDepProblems(FILE *fp, struct rpmDependencyConflict *conflicts,
+	int numConflicts)	/*@modifies *fp @*/;
+
+/**
+ */
+/*@only@*/ const char * rpmProblemString(rpmProblem prob)	/*@*/;
+
+/**
+ */
+void rpmProblemPrint(FILE *fp, rpmProblem prob)	/*@modifies *fp @*/;
+
+/**
+ */
+void rpmProblemSetPrint(FILE *fp, rpmProblemSet probs)	/*@modifies *fp @*/;
+
+/**
+ */
+void rpmProblemSetFree( /*@only@*/ rpmProblemSet probs);
+
+/*@}*/
 /* ==================================================================== */
+/** \name RPMTS */
+/*@{*/
 /* we pass these around as an array with a sentinel */
 typedef struct rpmRelocation_s {
-    const char * oldPath;	/* NULL here evals to RPMTAG_DEFAULTPREFIX, */
 				/* XXX for backwards compatibility */
-    const char * newPath;	/* NULL means to omit the file completely! */
+    const char * oldPath;	/*!< NULL here evals to RPMTAG_DEFAULTPREFIX, */
+    const char * newPath;	/*!< NULL means to omit the file completely! */
 } rpmRelocation;
 
 
@@ -629,38 +776,12 @@ int rpmInstallSourcePackage(const char * root, FD_t fd, const char ** specFile,
  */
 int rpmVersionCompare(Header first, Header second);
 
-
-/**
- * @param root		path to top of install tree
- * @param h		header
- */
-int rpmVerifyFile(const char * root, Header h, int filenum,
-	/*@out@*/ int * result, int omitMask);
-
-/**
- * @param root		path to top of install tree
- * @param h		header
- * @param err		file handle
- */
-int rpmVerifyScript(const char * root, Header h, FD_t err);
-
 /* Transaction sets are inherently unordered! RPM may reorder transaction
    sets to reduce errors. In general, installs/upgrades are done before
    strict removals, and prerequisite ordering is done on installs/upgrades. */
 typedef /*@abstract@*/ struct rpmTransactionSet_s * rpmTransactionSet;
 
-struct rpmDependencyConflict {
-    char * byName, * byVersion, * byRelease;
-    Header byHeader;
-    /* these needs fields are misnamed -- they are used for the package
-       which isn't needed as well */
-    char * needsName, * needsVersion;
-    int needsFlags;
-    /*@observer@*/ /*@null@*/ const void * suggestedPackage; /* NULL if none */
-    enum { RPMDEP_SENSE_REQUIRES, RPMDEP_SENSE_CONFLICTS } sense;
-} ;
-
-/**
+/** \ingroup rpmtrans
  * Create an empty transaction set.
  * @param rpmdb		rpm database (may be NULL if database is not accessed)
  * @param rootdir	path to top of install tree
@@ -669,7 +790,7 @@ struct rpmDependencyConflict {
 /*@only@*/ rpmTransactionSet rpmtransCreateSet( /*@only@*/ rpmdb rpmdb,
 	const char * rootdir);
 
-/**
+/** \ingroup rpmtrans
  * Add package to be installed to unordered transaction set.
  *
  * If fd is NULL, the callback specified in rpmtransCreateSet() is used to
@@ -689,7 +810,7 @@ int rpmtransAddPackage(rpmTransactionSet rpmdep, Header h, FD_t fd,
 		/*@owned@*/ const void * key, int update,
 		rpmRelocation * relocs);
 
-/**
+/** \ingroup rpmtrans
  * Add package to universe of possible packages to install in transaction set.
  * @param rpmdep	rpm transaction set
  * @param h		header
@@ -698,27 +819,27 @@ int rpmtransAddPackage(rpmTransactionSet rpmdep, Header h, FD_t fd,
 void rpmtransAvailablePackage(rpmTransactionSet rpmdep, Header h,
 		/*@owned@*/ const void * key);
 
-/**
+/** \ingroup rpmtrans
  * Add package to be removed to unordered transaction set.
  * @param rpmdep	rpm transaction set
  * @param dboffset	rpm database instance
  */
 void rpmtransRemovePackage(rpmTransactionSet rpmdep, int dboffset);
 
-/**
+/** \ingroup rpmtrans
  * Destroy transaction set.
  * @param rpmdep	rpm transaction set
  */
 void rpmtransFree( /*@only@*/ rpmTransactionSet rpmdep);
 
-/**
+/** \ingroup rpmtrans
  * @param ts		rpm transaction set
  * @param fd		file handle
  */
 void rpmtransSetScriptFd(rpmTransactionSet ts, FD_t fd);
 
 /* this checks for dependency satisfaction, but *not* ordering */
-/**
+/** \ingroup rpmtrans
  * @param rpmdep	rpm transaction set
  */
 int rpmdepCheck(rpmTransactionSet rpmdep,
@@ -729,12 +850,12 @@ int rpmdepCheck(rpmTransactionSet rpmdep,
    check is done, use rpmdepCheck() for that. If dependencies are not
    satisfied a "best-try" ordering is returned. */
 
-/**
+/** \ingroup rpmtrans
  * @param order		rpm transaction set
  */
 int rpmdepOrder(rpmTransactionSet order);
 
-/**
+/** \ingroup rpmtrans
  * Destroy dependency conflicts.
  * @param conflicts	dependency conflicts
  * @param numConflicts	no. of dependency conflicts
@@ -752,7 +873,7 @@ void rpmdepFreeConflicts( /*@only@*/ struct rpmDependencyConflict * conflicts,
 #define	RPMTRANS_FLAG_KEEPOBSOLETE	(1 << 7)
 #define	RPMTRANS_FLAG_MULTILIB		(1 << 8)
 
-/**
+/** \ingroup rpmdep
  * Compare two versioned dependency ranges, looking for overlap.
  * @param AName		1st dependncy name string
  * @param AEVR		1st dependency [epoch:]version[-release] string
@@ -765,7 +886,7 @@ void rpmdepFreeConflicts( /*@only@*/ struct rpmDependencyConflict * conflicts,
 int rpmRangesOverlap(const char *AName, const char *AEVR, int AFlags,
         const char *BName, const char *BEVR, int BFlags)	/*@*/;
 
-/**
+/** \ingroup rpmdep
  * Check dependency against internal rpmlib feature provides.
  * @param keyName	dependency name string
  * @param keyEVR	dependency [epoch:]version[-release] string
@@ -775,68 +896,13 @@ int rpmRangesOverlap(const char *AName, const char *AEVR, int AFlags,
 int rpmCheckRpmlibProvides(const char * keyName, const char * keyEVR,
 	int keyFlags)	/*@*/;
 
-/**
+/** \ingroup rpmcli
+ * Display current rpmlib feature provides.
+ * @param fp		output file handle
  */
 void rpmShowRpmlibProvides(FILE * fp) /*@modifies *fp @*/;
 
-/** */
-typedef enum rpmProblemType_e { RPMPROB_BADARCH, 
-				RPMPROB_BADOS,
-				RPMPROB_PKG_INSTALLED,
-				RPMPROB_BADRELOCATE,
-				RPMPROB_REQUIRES,
-				RPMPROB_CONFLICT,
-				RPMPROB_NEW_FILE_CONFLICT,
-				RPMPROB_FILE_CONFLICT,
-				RPMPROB_OLDPACKAGE,
-				RPMPROB_DISKSPACE,
-				RPMPROB_BADPRETRANS
- 			      } rpmProblemType;
-
-/** */
-typedef /*@abstract@*/ struct rpmProblem_s {
-    Header h, altH;
-/*@dependent@*/ const void * key;
-    rpmProblemType type;
-    int ignoreProblem;
-/*@only@*/ const char * str1;
-    unsigned long ulong1;
-} rpmProblem;
-
-/** */
-typedef /*@abstract@*/ struct rpmProblemSet_s {
-    int numProblems;
-    int numProblemsAlloced;
-    rpmProblem * probs;
-} * rpmProblemSet;
-
-/**
- */
-void printDepFlags(FILE *fp, const char *version, int flags)
-	/*@modifies *fp @*/;
-
-/**
- */
-void printDepProblems(FILE *fp, struct rpmDependencyConflict *conflicts,
-	int numConflicts)	/*@modifies *fp @*/;
-
-/**
- */
-/*@only@*/ const char * rpmProblemString(rpmProblem prob)	/*@*/;
-
-/**
- */
-void rpmProblemPrint(FILE *fp, rpmProblem prob)	/*@modifies *fp @*/;
-
-/**
- */
-void rpmProblemSetPrint(FILE *fp, rpmProblemSet probs)	/*@modifies *fp @*/;
-
-/**
- */
-void rpmProblemSetFree( /*@only@*/ rpmProblemSet probs);
-
-/**
+/** \ingroup rpmtrans
  * @param ts		rpm transaction set
  */
 int rpmRunTransactions(rpmTransactionSet ts, rpmCallbackFunction notify,
@@ -853,6 +919,8 @@ int rpmRunTransactions(rpmTransactionSet ts, rpmCallbackFunction notify,
 #define	RPMPROB_FILTER_OLDPACKAGE	(1 << 6)
 #define	RPMPROB_FILTER_DISKSPACE	(1 << 7)
 
+/*@}*/
+
 /** rpmlead.c **/
 
 #define	RPMLEAD_BINARY 0
@@ -867,6 +935,8 @@ int rpmRunTransactions(rpmTransactionSet ts, rpmCallbackFunction notify,
 
 #define	RPMLEAD_SIZE 96
 
+/** \ingroup lead
+ */
 struct rpmlead {
     unsigned char magic[4];
     unsigned char major, minor;
@@ -878,6 +948,8 @@ struct rpmlead {
     char reserved[16];      /* pads to 96 bytes -- 8 byte aligned! */
 } ;
 
+/** \ingroup lead
+ */
 struct oldrpmlead {		/* for version 1 packages */
     unsigned char magic[4];
     unsigned char major, minor;
@@ -889,69 +961,6 @@ struct oldrpmlead {		/* for version 1 packages */
     unsigned int archiveOffset;
 } ;
 
-/** signature.c **/
-
-/**************************************************/
-/*                                                */
-/* Signature Tags                                 */
-/*                                                */
-/* These go in the sig Header to specify          */
-/* individual signature types.                    */
-/*                                                */
-/**************************************************/
-
-#define	RPMSIGTAG_SIZE         	        1000
-/* the md5 sum was broken *twice* on big endian machines */
-#define	RPMSIGTAG_LEMD5_1		1001
-#define	RPMSIGTAG_PGP          	        1002
-#define	RPMSIGTAG_LEMD5_2		1003
-#define	RPMSIGTAG_MD5		        1004
-#define	RPMSIGTAG_GPG		        1005
-#define	RPMSIGTAG_PGP5		        1006	/* XXX legacy use only */
-
-/* Signature tags by Public Key Algorithm (RFC 2440) */
-/* N.B.: These tags are tenative, the values may change */
-#define	RPMTAG_PK_BASE			2048
-#define	RPMTAG_PK_RSA_ES		RPMTAG_PK_BASE+1
-#define	RPMTAG_PK_RSA_E			RPMTAG_PK_BASE+2
-#define	RPMTAG_PK_RSA_S			RPMTAG_PK_BASE+3
-#define	RPMTAG_PK_ELGAMAL_E		RPMTAG_PK_BASE+16
-#define	RPMTAG_PK_DSA			RPMTAG_PK_BASE+17
-#define	RPMTAG_PK_ELLIPTIC		RPMTAG_PK_BASE+18
-#define	RPMTAG_PK_ECDSA			RPMTAG_PK_BASE+19
-#define	RPMTAG_PK_ELGAMAL_ES		RPMTAG_PK_BASE+20
-#define	RPMTAG_PK_DH			RPMTAG_PK_BASE+21
-
-#define	RPMTAG_HASH_BASE		2048+64
-#define	RPMTAG_HASH_MD5			RPMTAG_HASH_BASE+1
-#define	RPMTAG_HASH_SHA1		RPMTAG_HASH_BASE+2
-#define	RPMTAG_HASH_RIPEMD160		RPMTAG_HASH_BASE+3
-#define	RPMTAG_HASH_MD2			RPMTAG_HASH_BASE+5
-#define	RPMTAG_HASH_TIGER192		RPMTAG_HASH_BASE+6
-#define	RPMTAG_HASH_HAVAL_5_160		RPMTAG_HASH_BASE+7
-
-/**************************************************/
-/*                                                */
-/* verifySignature() results                      */
-/*                                                */
-/**************************************************/
-
-/* verifySignature() results */
-#define	RPMSIG_OK		0
-#define	RPMSIG_UNKNOWN		1
-#define	RPMSIG_BAD		2
-#define	RPMSIG_NOKEY		3  /* Do not have the key to check this signature */
-#define	RPMSIG_NOTTRUSTED	4  /* We have the key but it is not trusted */
-
-/**
- */
-void rpmFreeSignature(Header h);
-
-/**
- */
-int rpmVerifySignature(const char *file, int_32 sigTag, void *sig, int count,
-		       char *result);
-
 /**
  */
 void freeFilesystems(void);
@@ -966,8 +975,12 @@ int rpmGetFilesystemUsage(const char ** filelist, int_32 * fssizes,
 	int numFiles, /*@out@*/ uint_32 ** usagesPtr, int flags);
 
 /* ==================================================================== */
+/** \name RPMBT */
+/*@{*/
 /* --- build mode options */
 
+/** \ingroup rpmcli
+ */
 struct rpmBuildArguments {
     int buildAmount;
     const char *buildRootOverride;
@@ -978,22 +991,50 @@ struct rpmBuildArguments {
     int shortCircuit;
     char buildMode;
     char buildChar;
-    /*@dependent@*/ const char *rootdir;
+/*@dependent@*/ const char *rootdir;
 };
+/** \ingroup rpmcli
+ */
 typedef	struct rpmBuildArguments BTA_t;
 
+/** \ingroup rpmcli
+ */
 extern struct rpmBuildArguments         rpmBTArgs;
 
+/** \ingroup rpmcli
+ */
 extern struct poptOption		rpmBuildPoptTable[];
 
+/*@}*/
 /* ==================================================================== */
+/** \name RPMQV */
+/*@{*/
+
+/** \ingroup rpmcli
+ * @param root		path to top of install tree
+ * @param h		header
+ */
+int rpmVerifyFile(const char * root, Header h, int filenum,
+	/*@out@*/ int * result, int omitMask);
+
+/** \ingroup rpmcli
+ * @param root		path to top of install tree
+ * @param h		header
+ * @param err		file handle
+ */
+int rpmVerifyScript(const char * root, Header h, FD_t err);
+
 /* --- query/verify mode options */
 
 /* XXX SPECFILE is not verify sources */
+/** \ingroup rpmcli
+ */
 enum rpmQVSources { RPMQV_PACKAGE = 0, RPMQV_PATH, RPMQV_ALL, RPMQV_RPM, 
 		       RPMQV_GROUP, RPMQV_WHATPROVIDES, RPMQV_WHATREQUIRES,
 		       RPMQV_TRIGGEREDBY, RPMQV_DBOFFSET, RPMQV_SPECFILE };
 
+/** \ingroup rpmcli
+ */
 struct rpmQVArguments {
     enum rpmQVSources qva_source;
     int 	qva_sourceCount;	/* > 1 is an error */
@@ -1004,20 +1045,26 @@ struct rpmQVArguments {
     char	qva_mode;
     char	qva_char;
 };
+/** \ingroup rpmcli
+ */
 typedef	struct rpmQVArguments QVA_t;
 
+/** \ingroup rpmcli
+ */
 extern struct rpmQVArguments		rpmQVArgs;
 
+/** \ingroup rpmcli
+ */
 extern struct poptOption		rpmQVSourcePoptTable[];
 
-/**
+/** \ingroup rpmcli
  * @param qva		parsed query/verify options
  * @param db		rpm database
  * @param h		header to use for query/verify
  */
 typedef	int (*QVF_t) (QVA_t *qva, rpmdb db, Header h);
 
-/**
+/** \ingroup rpmcli
  * @param qva		parsed query/verify options
  * @param mi		rpm database iterator
  * @param showPackage	query/verify routine
@@ -1043,15 +1090,20 @@ int showMatches(QVA_t *qva, /*@only@*/ /*@null@*/ rpmdbMatchIterator mi,
  */
 int tagValue(const char *tagstr)			/*@*/;
 
+/** \ingroup rpmcli
+ */
 extern int specedit;
+
+/** \ingroup rpmcli
+ */
 extern struct poptOption rpmQueryPoptTable[];
 
-/**
+/** \ingroup rpmcli
  * @param f	file handle to use for display
  */
 void rpmDisplayQueryTags(FILE * f);
 
-/**
+/** \ingroup rpmcli
  * @param qva		parsed query/verify options
  * @param source	type of source to query/verify
  * @param arg		name of source to query/verify
@@ -1061,14 +1113,14 @@ void rpmDisplayQueryTags(FILE * f);
 int rpmQueryVerify(QVA_t *qva, enum rpmQVSources source, const char * arg,
 	rpmdb db, QVF_t showPackage);
 
-/**
+/** \ingroup rpmcli
  * @param qva		parsed query/verify options
  * @param db		rpm database (unused for queries)
  * @param h		header to use for query
  */
 int showQueryPackage(QVA_t *qva, rpmdb db, Header h);
 
-/**
+/** \ingroup rpmcli
  * @param qva		parsed query/verify options
  * @param source	type of source to query
  * @param arg		name of source to query
@@ -1080,23 +1132,28 @@ int rpmQuery(QVA_t *qva, enum rpmQVSources source, const char * arg);
 #define	VERIFY_SCRIPT		(1 << 11)
 #define	VERIFY_MD5		(1 << 12)
 
+/** \ingroup rpmcli
+ */
 extern struct poptOption rpmVerifyPoptTable[];
 
-/**
+/** \ingroup rpmcli
  * @param qva		parsed query/verify options
  * @param db		rpm database
  * @param h		header to use for verify
  */
 int showVerifyPackage(QVA_t *qva, /*@only@*/ rpmdb db, Header h);
 
-/**
+/** \ingroup rpmcli
  * @param qva		parsed query/verify options
  * @param source	type of source to verify
  * @param arg		name of source to verify
  */
 int rpmVerify(QVA_t *qva, enum rpmQVSources source, const char *arg);
 
+/*@}*/
 /* ==================================================================== */
+/** \name RPMEIU */
+/*@{*/
 /* --- install/upgrade/erase modes */
 
 #define	INSTALL_PERCENT		(1 << 0)
@@ -1111,38 +1168,105 @@ int rpmVerify(QVA_t *qva, enum rpmQVSources source, const char *arg);
 #define	UNINSTALL_ALLMATCHES	(1 << 1)
 
 
-/**
+/** \ingroup rpmcli
  * @param rootdir	path to top of install tree
  * @param argv		array of package file names (NULL terminated)
  */
 int rpmInstall(const char * rootdir, const char ** argv, int installFlags, 
 	      int interfaceFlags, int probFilter, rpmRelocation * relocations);
 
-/**
+/** \ingroup rpmcli
  */
 int rpmInstallSource(const char * prefix, const char * arg, const char ** specFile,
 		    char ** cookie);
 
-/**
+/** \ingroup rpmcli
  * @param rootdir	path to top of install tree
  * @param argv		array of package file names (NULL terminated)
  */
 int rpmErase(const char * rootdir, const char ** argv, int uninstallFlags, 
 		 int interfaceFlags);
 
+/*@}*/
 /* ==================================================================== */
+/** \name RPMK */
+/*@{*/
+
+/** signature.c **/
+
+/**************************************************/
+/*                                                */
+/* Signature Tags                                 */
+/*                                                */
+/* These go in the sig Header to specify          */
+/* individual signature types.                    */
+/*                                                */
+/**************************************************/
+
+#define	RPMSIGTAG_SIZE         	        1000
+/* the md5 sum was broken *twice* on big endian machines */
+#define	RPMSIGTAG_LEMD5_1		1001
+#define	RPMSIGTAG_PGP          	        1002
+#define	RPMSIGTAG_LEMD5_2		1003
+#define	RPMSIGTAG_MD5		        1004
+#define	RPMSIGTAG_GPG		        1005
+#define	RPMSIGTAG_PGP5		        1006	/* XXX legacy use only */
+
+/* Signature tags by Public Key Algorithm (RFC 2440) */
+/* N.B.: These tags are tenative, the values may change */
+#define	RPMTAG_PK_BASE			2048
+#define	RPMTAG_PK_RSA_ES		RPMTAG_PK_BASE+1
+#define	RPMTAG_PK_RSA_E			RPMTAG_PK_BASE+2
+#define	RPMTAG_PK_RSA_S			RPMTAG_PK_BASE+3
+#define	RPMTAG_PK_ELGAMAL_E		RPMTAG_PK_BASE+16
+#define	RPMTAG_PK_DSA			RPMTAG_PK_BASE+17
+#define	RPMTAG_PK_ELLIPTIC		RPMTAG_PK_BASE+18
+#define	RPMTAG_PK_ECDSA			RPMTAG_PK_BASE+19
+#define	RPMTAG_PK_ELGAMAL_ES		RPMTAG_PK_BASE+20
+#define	RPMTAG_PK_DH			RPMTAG_PK_BASE+21
+
+#define	RPMTAG_HASH_BASE		2048+64
+#define	RPMTAG_HASH_MD5			RPMTAG_HASH_BASE+1
+#define	RPMTAG_HASH_SHA1		RPMTAG_HASH_BASE+2
+#define	RPMTAG_HASH_RIPEMD160		RPMTAG_HASH_BASE+3
+#define	RPMTAG_HASH_MD2			RPMTAG_HASH_BASE+5
+#define	RPMTAG_HASH_TIGER192		RPMTAG_HASH_BASE+6
+#define	RPMTAG_HASH_HAVAL_5_160		RPMTAG_HASH_BASE+7
+
+/**************************************************/
+/*                                                */
+/* verifySignature() results                      */
+/*                                                */
+/**************************************************/
+
+/* verifySignature() results */
+#define	RPMSIG_OK		0
+#define	RPMSIG_UNKNOWN		1
+#define	RPMSIG_BAD		2
+#define	RPMSIG_NOKEY		3  /* Do not have the key to check this signature */
+#define	RPMSIG_NOTTRUSTED	4  /* We have the key but it is not trusted */
+
+/** \ingroup signature
+ */
+void rpmFreeSignature(Header h);
+
+/** \ingroup signature
+ */
+int rpmVerifySignature(const char *file, int_32 sigTag, void *sig, int count,
+		       char *result);
+
 /* --- checksig/resign */
 
 #define	CHECKSIG_PGP (1 << 0)
 #define	CHECKSIG_MD5 (1 << 1)
 #define	CHECKSIG_GPG (1 << 2)
 
-/**
+/** \ingroup rpmcli
  * @param argv		array of package file names (NULL terminated)
  */
 int rpmCheckSig(int flags, const char ** argv);
 
-/**
+/** \ingroup rpmcli
  * @param argv		array of package file names (NULL terminated)
  */
 int rpmReSign(int add, char *passPhrase, const char ** argv);
@@ -1150,6 +1274,8 @@ int rpmReSign(int add, char *passPhrase, const char ** argv);
 #define	ADD_SIGNATURE 1
 #define	NEW_SIGNATURE 0
 
+/*@}*/
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/lib/rpmlibprov.c b/lib/rpmlibprov.c
index 11e8d5a9f..1da8cc3d1 100644
--- a/lib/rpmlibprov.c
+++ b/lib/rpmlibprov.c
@@ -1,3 +1,7 @@
+/** \ingroup rpmdep
+ * \file lib/rpmlibprov.c
+ */
+
 #include "system.h"
 
 #include <rpmlib.h>
diff --git a/lib/signature.c b/lib/signature.c
index 8005e400a..0042eb9cd 100644
--- a/lib/signature.c
+++ b/lib/signature.c
@@ -1,3 +1,7 @@
+/** \ingroup signature
+ * \file lib/signature.c
+ */
+
 /* signature.c - RPM signature functions */
 
 /* NOTES
diff --git a/lib/signature.h b/lib/signature.h
index 03cedd469..40f6d6509 100644
--- a/lib/signature.h
+++ b/lib/signature.h
@@ -1,7 +1,9 @@
 #ifndef H_SIGNATURE
 #define	H_SIGNATURE
 
-/* signature.h - generate and verify signatures */
+/** \file lib/signature.h
+ * Generate and verify signatures.
+ */
 
 #include <header.h>
 
diff --git a/lib/stringbuf.c b/lib/stringbuf.c
index 548c745dc..afd223e77 100644
--- a/lib/stringbuf.c
+++ b/lib/stringbuf.c
@@ -1,3 +1,7 @@
+/**
+ * \file lib/stringbuf.c
+ */
+
 #include "system.h"
 
 #include "stringbuf.h"
diff --git a/lib/stringbuf.h b/lib/stringbuf.h
index 9b658ba8e..95474cbde 100644
--- a/lib/stringbuf.h
+++ b/lib/stringbuf.h
@@ -1,6 +1,10 @@
 #ifndef _STRINGBUF_H_
 #define _STRINGBUF_H_
 
+/** \file lib/stringbuf.h
+ *
+ */
+
 typedef /*@abstract@*/ struct StringBufRec *StringBuf;
 
 #ifdef __cplusplus
diff --git a/lib/stubs.c b/lib/stubs.c
index 9a89691bd..a921d0a40 100644
--- a/lib/stubs.c
+++ b/lib/stubs.c
@@ -1,3 +1,7 @@
+/**
+ * \file lib/stubs.c
+ */
+
 /* XXX Portable shared libraries require rpmlib to contain these functions. */
 
 #include "system.h"
diff --git a/lib/tagName.c b/lib/tagName.c
index 202914d6c..365db28f9 100644
--- a/lib/tagName.c
+++ b/lib/tagName.c
@@ -1,3 +1,7 @@
+/**
+ * \file lib/tagName.c
+ */
+
 #include "system.h"
 
 #include <rpmlib.h>
diff --git a/lib/tufdio.c b/lib/tufdio.c
index 0e266be09..ef64fb4b9 100644
--- a/lib/tufdio.c
+++ b/lib/tufdio.c
@@ -1,3 +1,7 @@
+/** \ingroup rpmio
+ * \file lib/tufdio.c
+ */
+
 #include "system.h"
 
 #include <rpmlib.h>
diff --git a/lib/uninstall.c b/lib/uninstall.c
index ef14682c3..09384c57a 100644
--- a/lib/uninstall.c
+++ b/lib/uninstall.c
@@ -1,3 +1,7 @@
+/** \ingroup rpmtrans payload
+ * \file lib/uninstall.c
+ */
+
 #include "system.h"
 
 #include <rpmlib.h>
@@ -157,7 +161,7 @@ int removeBinaryPackage(const char * rootdir, rpmdb rpmdb, unsigned int offset,
 		if (fnlen > fnmaxlen)
 		    fnmaxlen = fnlen;
 	}
-	fnmaxlen += rootdir + sizeof("/");	/* XXX one byte too many */
+	fnmaxlen += rdlen + sizeof("/");	/* XXX one byte too many */
 
 	fileName = alloca(fnmaxlen);
 
diff --git a/lib/verify.c b/lib/verify.c
index c35ba568f..669242f35 100644
--- a/lib/verify.c
+++ b/lib/verify.c
@@ -1,3 +1,7 @@
+/** \ingroup rpmcli
+ * \file lib/verify.c
+ */
+
 #include "system.h"
 
 #include <rpmlib.h>