doxygen annotations for build/*.

- fix: don't hang on build error.
- fix: remove "error: " prefix from signature verification message.

CVS patchset: 4426
CVS date: 2001/01/11 14:13:04

16 files changed, 454 insertions, 179 deletions

diff --git a/build/build.c b/build/build.c
index cda5f67ad..3f8ce87b7 100644
--- a/build/build.c
+++ b/build/build.c
@@ -12,6 +12,8 @@
 
 static int _build_debug = 0;
 
+/**
+ */
 static void doRmSource(Spec spec)
 {
     struct Source *p;
@@ -41,9 +43,8 @@ static void doRmSource(Spec spec)
 }
 
 /*
- * The _preScript string is expanded to export values to a script environment.
+ * @todo Single use by %%doc in files.c prevents static.
  */
-/** */
 int doScript(Spec spec, int what, const char *name, StringBuf sb, int test)
 {
     const char * rootURL = spec->rootURL;
diff --git a/build/expression.c b/build/expression.c
index 7179ac056..1884905ad 100644
--- a/build/expression.c
+++ b/build/expression.c
@@ -27,12 +27,10 @@
 #define DEBUG(x)
 #endif
 
-/*
+/**
  * Encapsulation of a "value"
  */
-
-typedef struct _value
-{
+typedef struct _value {
   enum { VALUE_TYPE_INTEGER, VALUE_TYPE_STRING } type;
   union {
     const char *s;
@@ -40,6 +38,8 @@ typedef struct _value
   } data;
 } *Value;
 
+/**
+ */
 static Value valueMakeInteger(int i)
 {
   Value v;
@@ -50,6 +50,8 @@ static Value valueMakeInteger(int i)
   return v;
 }
 
+/**
+ */
 static Value valueMakeString(/*@only@*/ const char *s)
 {
   Value v;
@@ -60,6 +62,8 @@ static Value valueMakeString(/*@only@*/ const char *s)
   return v;
 }
 
+/**
+ */
 static void valueFree( /*@only@*/ Value v)
 {
   if (v) {
@@ -88,23 +92,22 @@ static void valueDump(const char *msg, Value v, FILE *fp)
 #define valueSameType(v1,v2) ((v1)->type == (v2)->type)
 
 
-/*
+/**
  * Parser state.
  */
-
 typedef struct _parseState {
-  /*@owned@*/ char *str;	/* expression string */
-  /*@dependent@*/ char *p;	/* current position in expression string */
-  int nextToken;		/* current lookahead token */
-  Value tokenValue;		/* valid when TOK_INTEGER or TOK_STRING */
-  Spec spec;			/* spec file that we are parsing inside of */
+  /*@owned@*/ char *str;	/*!< expression string */
+  /*@dependent@*/ char *p;	/*!< current position in expression string */
+  int nextToken;		/*!< current lookahead token */
+  Value tokenValue;		/*!< valid when TOK_INTEGER or TOK_STRING */
+  Spec spec;			/*!< spec file that we are parsing inside of */
 } *ParseState;
 
 
-/*
- * Token parser.
+/**
+ * \name Parser tokens
  */
-
+/*@{*/
 #define TOK_EOF          1
 #define TOK_INTEGER      2
 #define TOK_STRING       3
@@ -124,6 +127,7 @@ typedef struct _parseState {
 #define TOK_NOT         17
 #define TOK_LOGICAL_AND 18
 #define TOK_LOGICAL_OR  19
+/*@}*/
 
 #define	EXPRBUFSIZ	BUFSIZ
 
@@ -168,6 +172,9 @@ static const char *prToken(int val)
 }
 #endif	/* DEBUG_PARSER */
 
+/**
+ * @param state		expression parser state
+ */
 static int rdToken(ParseState state)
 {
   int token;
@@ -301,6 +308,9 @@ static int rdToken(ParseState state)
 
 static Value doLogical(ParseState state);
 
+/**
+ * @param state		expression parser state
+ */
 static Value doPrimary(ParseState state)
 {
   Value v;
@@ -374,6 +384,9 @@ static Value doPrimary(ParseState state)
   return v;
 }
 
+/**
+ * @param state		expression parser state
+ */
 static Value doMultiplyDivide(ParseState state)
 {
   Value v1, v2 = NULL;
@@ -420,6 +433,9 @@ static Value doMultiplyDivide(ParseState state)
   return v1;
 }
 
+/**
+ * @param state		expression parser state
+ */
 static Value doAddSubtract(ParseState state)
 {
   Value v1, v2 = NULL;
@@ -475,6 +491,9 @@ static Value doAddSubtract(ParseState state)
   return v1;
 }
 
+/**
+ * @param state		expression parser state
+ */
 static Value doRelational(ParseState state)
 {
   Value v1, v2 = NULL;
@@ -563,6 +582,9 @@ static Value doRelational(ParseState state)
   return v1;
 }
 
+/**
+ * @param state		expression parser state
+ */
 static Value doLogical(ParseState state)
 {
   Value v1, v2 = NULL;
@@ -609,8 +631,7 @@ static Value doLogical(ParseState state)
   return v1;
 }
 
-/** */
-int parseExpressionBoolean(Spec spec, char *expr)
+int parseExpressionBoolean(Spec spec, const char *expr)
 {
   struct _parseState state;
   int result = -1;
@@ -657,8 +678,7 @@ int parseExpressionBoolean(Spec spec, char *expr)
   return result;
 }
 
-/** */
-char * parseExpressionString(Spec spec, char *expr)
+char * parseExpressionString(Spec spec, const char *expr)
 {
   struct _parseState state;
   char *result = NULL;
diff --git a/build/files.c b/build/files.c
index ad7dc21f9..140dd8d3f 100644
--- a/build/files.c
+++ b/build/files.c
@@ -26,6 +26,8 @@
 
 #define MAXDOCDIR 1024
 
+/**
+ */
 typedef struct {
     struct stat fl_st;
 #define	fl_dev	fl_st.st_dev
@@ -47,6 +49,8 @@ typedef struct {
     const char *langs;	/* XXX locales separated with | */
 } FileListRec;
 
+/**
+ */
 typedef struct {
     const char *ar_fmodestr;
     const char *ar_dmodestr;
@@ -56,8 +60,12 @@ typedef struct {
     mode_t	ar_dmode;
 } AttrRec;
 
+/**
+ */
 static int multiLib = 0;	/* MULTILIB */
 
+/**
+ */
 struct FileList {
     const char *buildRootURL;
     const char *prefix;
@@ -89,6 +97,8 @@ struct FileList {
     int fileListRecsUsed;
 };
 
+/**
+ */
 static void nullAttrRec(/*@out@*/AttrRec *ar)
 {
     ar->ar_fmodestr = NULL;
@@ -99,6 +109,8 @@ static void nullAttrRec(/*@out@*/AttrRec *ar)
     ar->ar_dmode = 0;
 }
 
+/**
+ */
 static void freeAttrRec(AttrRec *ar)
 {
     FREE(ar->ar_fmodestr);
@@ -108,6 +120,8 @@ static void freeAttrRec(AttrRec *ar)
     /* XXX doesn't free ar (yet) */
 }
 
+/**
+ */
 static void dupAttrRec(AttrRec *oar, /*@out@*/ AttrRec *nar)
 {
     if (oar == nar)	/* XXX pathological paranoia */
@@ -122,6 +136,8 @@ static void dupAttrRec(AttrRec *oar, /*@out@*/ AttrRec *nar)
 }
 
 #if 0
+/**
+ */
 static void dumpAttrRec(const char *msg, AttrRec *ar) {
     if (msg)
 	fprintf(stderr, "%s:\t", msg);
@@ -152,6 +168,8 @@ static void dumpAttrRec(const char *msg, AttrRec *ar) {
    not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
    Boston, MA 02111-1307, USA.  */
 
+/**
+ */
 static char *strtokWithQuotes(char *s, char *delim)
 {
     static char *olds = NULL;
@@ -190,6 +208,8 @@ static char *strtokWithQuotes(char *s, char *delim)
     return token;
 }
 
+/**
+ */
 static void timeCheck(int tc, Header h)
 {
     int *mtime;
@@ -209,12 +229,15 @@ static void timeCheck(int tc, Header h)
     FREE(files);
 }
 
+/**
+ */
 typedef struct VFA {
 	char *	attribute;
 	int	flag;
 } VFA_t;
 
-/** */
+/**
+ */
 VFA_t verifyAttrs[] = {
 	{ "md5",	RPMVERIFY_MD5 },
 	{ "size",	RPMVERIFY_FILESIZE },
@@ -227,6 +250,8 @@ VFA_t verifyAttrs[] = {
 	{ NULL, 0 }
 };
 
+/**
+ */
 static int parseForVerify(char *buf, struct FileList *fl)
 {
     char *p, *pe, *q;
@@ -310,6 +335,8 @@ static int parseForVerify(char *buf, struct FileList *fl)
 
 #define	isAttrDefault(_ars)	((_ars)[0] == '-' && (_ars)[1] == '\0')
 
+/**
+ */
 static int parseForAttr(char *buf, struct FileList *fl)
 {
     char *p, *pe, *q;
@@ -425,6 +452,8 @@ static int parseForAttr(char *buf, struct FileList *fl)
     return 0;
 }
 
+/**
+ */
 static int parseForConfig(char *buf, struct FileList *fl)
 {
     char *p, *pe, *q;
@@ -481,6 +510,8 @@ static int parseForConfig(char *buf, struct FileList *fl)
     return 0;
 }
 
+/**
+ */
 static int parseForLang(char *buf, struct FileList *fl)
 {
     char *p, *pe, *q;
@@ -561,6 +592,8 @@ static int parseForLang(char *buf, struct FileList *fl)
     return 0;
 }
 
+/**
+ */
 static int parseForRegexLang(const char *fileName, /*@out@*/char **lang)
 {
     static int initialized = 0;
@@ -600,6 +633,8 @@ static int parseForRegexLang(const char *fileName, /*@out@*/char **lang)
     return 0;
 }
 
+/**
+ */
 static int parseForRegexMultiLib(const char *fileName)
 {
     static int initialized = 0;
@@ -628,7 +663,8 @@ static int parseForRegexMultiLib(const char *fileName)
     return 0;
 }
 
-/** */
+/**
+ */
 VFA_t virtualFileAttributes[] = {
 	{ "%dir",	0 },	/* XXX why not RPMFILE_DIR? */
 	{ "%doc",	RPMFILE_DOC },
@@ -648,6 +684,8 @@ VFA_t virtualFileAttributes[] = {
 	{ NULL, 0 }
 };
 
+/**
+ */
 static int parseForSimple(/*@unused@*/Spec spec, Package pkg, char *buf,
 			  struct FileList *fl, const char **fileName)
 {
@@ -763,6 +801,8 @@ static int parseForSimple(/*@unused@*/Spec spec, Package pkg, char *buf,
     return res;
 }
 
+/**
+ */
 static int compareFileListRecs(const void *ap, const void *bp)
 {
     const char *a = ((FileListRec *)ap)->fileURL;
@@ -770,6 +810,8 @@ static int compareFileListRecs(const void *ap, const void *bp)
     return strcmp(a, b);
 }
 
+/**
+ */
 static int isDoc(struct FileList *fl, const char *fileName)
 {
     int x = fl->docDirCount;
@@ -960,6 +1002,8 @@ static void genCpioListAndHeader(struct FileList *fl,
 		       &multiLibMask, 1);
 }
 
+/**
+ */
 static void freeFileList(FileListRec *fileList, int count)
 {
     while (count--) {
@@ -970,6 +1014,8 @@ static void freeFileList(FileListRec *fileList, int count)
     FREE(fileList);
 }
 
+/**
+ */
 static int addFile(struct FileList *fl, const char * diskURL, struct stat *statp)
 {
     const char *fileURL = diskURL;
@@ -1139,6 +1185,8 @@ static int addFile(struct FileList *fl, const char * diskURL, struct stat *statp
     return 0;
 }
 
+/**
+ */
 static int processBinaryFile(/*@unused@*/Package pkg, struct FileList *fl,
 	const char *fileURL)
 {
@@ -1196,6 +1244,8 @@ exit:
     return rc;
 }
 
+/**
+ */
 static int processPackageFiles(Spec spec, Package pkg,
 			       int installSpecialDoc, int test)
 {
@@ -1600,6 +1650,8 @@ int processSourceFiles(Spec spec)
     return fl.processingFailed;
 }
 
+/**
+ */
 static StringBuf getOutputFrom(char *dir, char *argv[],
 			const char *writePtr, int writeBytesLeft,
 			int failNonZero)
@@ -1732,7 +1784,8 @@ top:
     return readBuff;
 }
 
-/** */
+/**
+ */
 typedef struct {
     const char *msg;
     const char *argv[4];
@@ -1743,7 +1796,8 @@ typedef struct {
     int xor;
 } DepMsg_t;
 
-/** */
+/**
+ */
 DepMsg_t depMsgs[] = {
   { "Provides",		{ "%{__find_provides}", NULL, NULL, NULL },
 	RPMTAG_PROVIDENAME, RPMTAG_PROVIDEVERSION, RPMTAG_PROVIDEFLAGS,
@@ -1784,6 +1838,8 @@ DepMsg_t depMsgs[] = {
   { NULL,		{ NULL, NULL, NULL, NULL },	0, 0, 0, 0, 0 }
 };
 
+/**
+ */
 static int generateDepends(Spec spec, Package pkg,
 			   struct cpioFileMapping *cpioList, int cpioCount,
 			   int multiLib)
@@ -1898,6 +1954,8 @@ static int generateDepends(Spec spec, Package pkg,
     return rc;
 }
 
+/**
+ */
 static void printDepMsg(DepMsg_t *dm, int count, const char **names,
 	const char **versions, int *flags)
 {
@@ -1937,6 +1995,8 @@ static void printDepMsg(DepMsg_t *dm, int count, const char **names,
 	rpmMessage(RPMMESS_NORMAL, "\n");
 }
 
+/**
+ */
 static void printDeps(Header h)
 {
     const char **names = NULL;
diff --git a/build/misc.c b/build/misc.c
index 1e6b026e4..459410832 100644
--- a/build/misc.c
+++ b/build/misc.c
@@ -6,16 +6,10 @@
 #include "rpmbuild.h"
 #include "debug.h"
 
-/** */
 int parseNum(const char *line, int *res)
 {
-    char *s1;
-    
-    s1 = NULL;
-    *res = strtoul(line, &s1, 10);
-    if ((*s1) || (s1 == line) || (*res == ULONG_MAX)) {
-	return 1;
-    }
+    char * s1 = NULL;
 
-    return 0;
+    *res = strtoul(line, &s1, 10);
+    return (((*s1) || (s1 == line) || (*res == ULONG_MAX)) ? 1 : 0);
 }
diff --git a/build/myftw.c b/build/myftw.c
index dff0adac0..976a7f883 100644
--- a/build/myftw.c
+++ b/build/myftw.c
@@ -47,6 +47,8 @@ Cambridge, MA 02139, USA.  */
 
 /* Traverse one level of a directory tree.  */
 
+/**
+ */
 static int
 myftw_dir (DIR **dirs, int level, int descriptors,
 	   char *dir, size_t len, 
@@ -166,8 +168,6 @@ myftw_dir (DIR **dirs, int level, int descriptors,
 
 /* Call a function on every element in a directory tree.  */
 
-
-/** */
 int myftw (const char *dir,
 	   int descriptors,
 	   myftwFunc func,
diff --git a/build/pack.c b/build/pack.c
index 4ef703bc8..9074229e1 100644
--- a/build/pack.c
+++ b/build/pack.c
@@ -16,6 +16,8 @@
 
 extern int _noDirTokens;
 
+/**
+ */
 static inline int genSourceRpmName(Spec spec)
 {
     if (spec->sourceRpmName == NULL) {
@@ -31,6 +33,8 @@ static inline int genSourceRpmName(Spec spec)
     return 0;
 }
 
+/**
+ */
 static int cpio_doio(FD_t fdo, CSA_t * csa, const char * fmodeMacro)
 {
     FD_t cfd;
@@ -58,6 +62,8 @@ static int cpio_doio(FD_t fdo, CSA_t * csa, const char * fmodeMacro)
     return rc;
 }
 
+/**
+ */
 static int cpio_copy(FD_t fdo, CSA_t *csa)
 {
     char buf[BUFSIZ];
@@ -79,6 +85,8 @@ static int cpio_copy(FD_t fdo, CSA_t *csa)
     return 0;
 }
 
+/**
+ */
 static StringBuf addFileToTagAux(Spec spec, const char *file, StringBuf sb)
 {
     char buf[BUFSIZ];
@@ -107,6 +115,8 @@ static StringBuf addFileToTagAux(Spec spec, const char *file, StringBuf sb)
     return sb;
 }
 
+/**
+ */
 static int addFileToTag(Spec spec, const char *file, Header h, int tag)
 {
     StringBuf sb = newStringBuf();
@@ -126,6 +136,8 @@ static int addFileToTag(Spec spec, const char *file, Header h, int tag)
     return 0;
 }
 
+/**
+ */
 static int addFileToArrayTag(Spec spec, char *file, Header h, int tag)
 {
     StringBuf sb = newStringBuf();
@@ -141,6 +153,8 @@ static int addFileToArrayTag(Spec spec, char *file, Header h, int tag)
     return 0;
 }
 
+/**
+ */
 static int processScriptFiles(Spec spec, Package pkg)
 {
     struct TriggerFileEntry *p;
diff --git a/build/parseChangelog.c b/build/parseChangelog.c
index 3326d6fae..5e9123e3f 100644
--- a/build/parseChangelog.c
+++ b/build/parseChangelog.c
@@ -8,7 +8,6 @@
 #include "rpmbuild.h"
 #include "debug.h"
 
-/** */
 void addChangelogEntry(Header h, time_t time, const char *name, const char *text)
 {
     int_32 mytime = time;	/* XXX convert to header representation */
@@ -29,7 +28,12 @@ void addChangelogEntry(Header h, time_t time, const char *name, const char *text
     }
 }
 
-/* datestr is of the form 'Wed Jan 1 1997' */
+/**
+ * Parse date string to seconds.
+ * @param datestr	date string (e.g. 'Wed Jan 1 1997')
+ * @retval secs		secs since the unix epoch
+ * @return 		0 on success, -1 on error
+ */
 static int dateToTimet(const char * datestr, /*@out@*/ time_t * secs)
 {
     struct tm time;
@@ -92,6 +96,12 @@ static int dateToTimet(const char * datestr, /*@out@*/ time_t * secs)
     return 0;
 }
 
+/**
+ * Add %changelog section to header.
+ * @param h		header
+ * @param sb		changelog strings
+ * @return		0 on success
+ */
 static int addChangelog(Header h, StringBuf sb)
 {
     char *s;
@@ -185,7 +195,6 @@ static int addChangelog(Header h, StringBuf sb)
     return 0;
 }
 
-/** */
 int parseChangelog(Spec spec)
 {
     int nextPart, res, rc;
diff --git a/build/parseDescription.c b/build/parseDescription.c
index e889cf244..a5652e380 100644
--- a/build/parseDescription.c
+++ b/build/parseDescription.c
@@ -20,7 +20,6 @@ extern int noLang;		/* XXX FIXME: pass as arg */
 	{ 0, 0, 0, 0, 0,	NULL, NULL}
     };
 
-/** */
 int parseDescription(Spec spec)
 {
     int nextPart;
diff --git a/build/parsePreamble.c b/build/parsePreamble.c
index 8c64b66d0..2d7370878 100644
--- a/build/parsePreamble.c
+++ b/build/parsePreamble.c
@@ -9,6 +9,8 @@
 #include <rpmbuild.h>
 #include "debug.h"
 
+/**
+ */
 static int_32 copyTagsDuringParse[] = {
     RPMTAG_EPOCH,
     RPMTAG_VERSION,
@@ -27,6 +29,8 @@ static int_32 copyTagsDuringParse[] = {
     0
 };
 
+/**
+ */
 static int requiredTags[] = {
     RPMTAG_NAME,
     RPMTAG_VERSION,
@@ -37,6 +41,8 @@ static int requiredTags[] = {
     0
 };
 
+/**
+ */
 static void addOrAppendListEntry(Header h, int_32 tag, char *line)
 {
     int argc;
@@ -51,6 +57,8 @@ static void addOrAppendListEntry(Header h, int_32 tag, char *line)
 /* Parse a simple part line that only take -n <pkg> or <pkg> */
 /* <pkg> is return in name as a pointer into a static buffer */
 
+/**
+ */
 static int parseSimplePart(char *line, /*@out@*/char **name, /*@out@*/int *flag)
 {
     char *tok;
@@ -80,6 +88,8 @@ static int parseSimplePart(char *line, /*@out@*/char **name, /*@out@*/int *flag)
     return (strtok(NULL, " \t\n")) ? 1 : 0;
 }
 
+/**
+ */
 static inline int parseYesNo(const char *s)
 {
     return ((!s || (s[0] == 'n' || s[0] == 'N' || s[0] == '0') ||
@@ -92,6 +102,8 @@ struct tokenBits {
     int bits;
 };
 
+/**
+ */
 static struct tokenBits installScriptBits[] = {
     { "interp",		RPMSENSE_INTERP },
     { "prereq",		RPMSENSE_PREREQ },
@@ -104,6 +116,8 @@ static struct tokenBits installScriptBits[] = {
     { NULL, 0 }
 };
 
+/**
+ */
 static struct tokenBits buildScriptBits[] = {
     { "prep",		RPMSENSE_SCRIPT_PREP },
     { "build",		RPMSENSE_SCRIPT_BUILD },
@@ -112,6 +126,8 @@ static struct tokenBits buildScriptBits[] = {
     { NULL, 0 }
 };
 
+/**
+ */
 static int parseBits(const char * s, struct tokenBits * tokbits, int * bp)
 {
     struct tokenBits *tb;
@@ -143,6 +159,8 @@ static int parseBits(const char * s, struct tokenBits * tokbits, int * bp)
     return (c ? RPMERR_BADSPEC : 0);
 }
 
+/**
+ */
 static inline char * findLastChar(char * s)
 {
     char *res = s;
@@ -156,6 +174,8 @@ static inline char * findLastChar(char * s)
     return res;
 }
 
+/**
+ */
 static int isMemberInEntry(Header header, const char *name, int tag)
 {
     const char ** names;
@@ -171,6 +191,8 @@ static int isMemberInEntry(Header header, const char *name, int tag)
     return (count >= 0 ? 1 : 0);
 }
 
+/**
+ */
 static int checkForValidArchitectures(Spec spec)
 {
 #ifndef	DYING
@@ -208,6 +230,8 @@ static int checkForValidArchitectures(Spec spec)
     return 0;
 }
 
+/**
+ */
 static int checkForRequired(Header h, const char *name)
 {
     int res = 0;
@@ -224,6 +248,8 @@ static int checkForRequired(Header h, const char *name)
     return res;
 }
 
+/**
+ */
 static int checkForDuplicates(Header h, const char *name)
 {
     int res = 0;
@@ -249,6 +275,8 @@ static int checkForDuplicates(Header h, const char *name)
     return res;
 }
 
+/**
+ */
 static struct optionalTag {
     int		ot_tag;
     const char *ot_mac;
@@ -260,6 +288,8 @@ static struct optionalTag {
     { -1, NULL }
 };
 
+/**
+ */
 static void fillOutMainPackage(Header h)
 {
     struct optionalTag *ot;
@@ -274,6 +304,8 @@ static void fillOutMainPackage(Header h)
     }
 }
 
+/**
+ */
 static int readIcon(Header h, const char *file)
 {
     const char *fn = NULL;
@@ -330,7 +362,6 @@ exit:
     return rc;
 }
 
-/** */
 struct spectag *
 stashSt(Spec spec, Header h, int tag, const char *lang)
 {
@@ -369,6 +400,8 @@ if (multiToken) { \
 
 extern int noLang;	/* XXX FIXME: pass as arg */
 
+/**
+ */
 static int handlePreambleTag(Spec spec, Package pkg, int tag, const char *macro,
 			     const char *lang)
 {
@@ -615,6 +648,8 @@ static int handlePreambleTag(Spec spec, Package pkg, int tag, const char *macro,
 /* This table has to be in a peculiar order.  If one tag is the */
 /* same as another, plus a few letters, it must come first.     */
 
+/**
+ */
 static struct PreambleRec {
     int tag;
     int len;
@@ -664,6 +699,8 @@ static struct PreambleRec {
     {0, 0, 0, 0}
 };
 
+/**
+ */
 static inline void initPreambleList(void)
 {
     struct PreambleRec *p;
@@ -671,6 +708,8 @@ static inline void initPreambleList(void)
 	p->len = strlen(p->token);
 }
 
+/**
+ */
 static int findPreambleTag(Spec spec, /*@out@*/int *tag, /*@out@*/char **macro, char *lang)
 {
     char *s;
diff --git a/build/parseReqs.c b/build/parseReqs.c
index 225c7a679..1c760c2a9 100644
--- a/build/parseReqs.c
+++ b/build/parseReqs.c
@@ -8,6 +8,8 @@
 #include "rpmbuild.h"
 #include "debug.h"
 
+/**
+ */
 static struct ReqComp {
     char *token;
     int sense;
@@ -29,7 +31,6 @@ static struct ReqComp {
 #define	SKIPWHITE(_x)	{while(*(_x) && (isspace(*_x) || *(_x) == ',')) (_x)++;}
 #define	SKIPNONWHITE(_x){while(*(_x) &&!(isspace(*_x) || *(_x) == ',')) (_x)++;}
 
-/** */
 int parseRCPOT(Spec spec, Package pkg, const char *field, int tag,
 	       int index, int tagflags)
 {
diff --git a/build/parseScript.c b/build/parseScript.c
index ddd71d45e..d3a0bf100 100644
--- a/build/parseScript.c
+++ b/build/parseScript.c
@@ -8,6 +8,8 @@
 #include "rpmbuild.h"
 #include "debug.h"
 
+/**
+ */
 static int addTriggerIndex(Package pkg, const char *file, const char *script, const char *prog)
 {
     struct TriggerFileEntry *new;
diff --git a/build/parseSpec.c b/build/parseSpec.c
index 7c728c5e8..7a729dab7 100644
--- a/build/parseSpec.c
+++ b/build/parseSpec.c
@@ -38,6 +38,8 @@ static struct PartRec {
     {0, 0, 0}
 };
 
+/**
+ */
 static inline void initParts(struct PartRec *p)
 {
     for (; p->token != NULL; p++)
@@ -63,6 +65,8 @@ rpmParseState isPart(const char *line)
     return (p->token ? p->part : PART_NONE);
 }
 
+/**
+ */
 static int matchTok(const char *token, const char *line)
 {
     const char *b, *be = line;
@@ -91,6 +95,8 @@ void handleComments(char *s)
 	*s = '\0';
 }
 
+/**
+ */
 static void forceIncludeFile(Spec spec, const char * fileName)
 {
     OFI_t * ofi;
@@ -101,6 +107,8 @@ static void forceIncludeFile(Spec spec, const char * fileName)
     spec->fileStack = ofi;
 }
 
+/**
+ */
 static int copyNextLine(Spec spec, OFI_t *ofi, int strip)
 {
     char *last;
@@ -398,7 +406,7 @@ fprintf(stderr, "*** PS buildRootURL(%s) %p macro set to %s\n", spec->buildRootU
     /* in the spec's line buffer.  Except for parsePreamble(),   */
     /* which handles the initial entry into a spec file.         */
     
-    while (parsePart != PART_NONE) {
+    while (parsePart < PART_LAST && parsePart != PART_NONE) {
 	switch (parsePart) {
 	  case PART_PREAMBLE:
 	    parsePart = parsePreamble(spec, initialPackage);
diff --git a/build/reqprov.c b/build/reqprov.c
index b9ff99e4c..5ee4b96a9 100644
--- a/build/reqprov.c
+++ b/build/reqprov.c
@@ -8,9 +8,8 @@
 #include "rpmbuild.h"
 #include "debug.h"
 
-/** */
 int addReqProv(/*@unused@*/ Spec spec, Header h,
-	       int flag, const char *name, const char *version, int index)
+	       int depFlags, const char *depName, const char *depEVR, int index)
 {
     const char **names;
     int nametag = 0;
@@ -20,41 +19,41 @@ int addReqProv(/*@unused@*/ Spec spec, Header h,
     int len;
     int extra = 0;
     
-    if (flag & RPMSENSE_PROVIDES) {
+    if (depFlags & RPMSENSE_PROVIDES) {
 	nametag = RPMTAG_PROVIDENAME;
 	versiontag = RPMTAG_PROVIDEVERSION;
 	flagtag = RPMTAG_PROVIDEFLAGS;
-	extra = flag & RPMSENSE_FIND_PROVIDES;
-    } else if (flag & RPMSENSE_OBSOLETES) {
+	extra = depFlags & RPMSENSE_FIND_PROVIDES;
+    } else if (depFlags & RPMSENSE_OBSOLETES) {
 	nametag = RPMTAG_OBSOLETENAME;
 	versiontag = RPMTAG_OBSOLETEVERSION;
 	flagtag = RPMTAG_OBSOLETEFLAGS;
-    } else if (flag & RPMSENSE_CONFLICTS) {
+    } else if (depFlags & RPMSENSE_CONFLICTS) {
 	nametag = RPMTAG_CONFLICTNAME;
 	versiontag = RPMTAG_CONFLICTVERSION;
 	flagtag = RPMTAG_CONFLICTFLAGS;
-    } else if (flag & RPMSENSE_PREREQ) {
+    } else if (depFlags & RPMSENSE_PREREQ) {
 	nametag = RPMTAG_REQUIRENAME;
 	versiontag = RPMTAG_REQUIREVERSION;
 	flagtag = RPMTAG_REQUIREFLAGS;
-	extra = flag & _ALL_REQUIRES_MASK;
-    } else if (flag & RPMSENSE_TRIGGER) {
+	extra = depFlags & _ALL_REQUIRES_MASK;
+    } else if (depFlags & RPMSENSE_TRIGGER) {
 	nametag = RPMTAG_TRIGGERNAME;
 	versiontag = RPMTAG_TRIGGERVERSION;
 	flagtag = RPMTAG_TRIGGERFLAGS;
 	indextag = RPMTAG_TRIGGERINDEX;
-	extra = flag & RPMSENSE_TRIGGER;
+	extra = depFlags & RPMSENSE_TRIGGER;
     } else {
 	nametag = RPMTAG_REQUIRENAME;
 	versiontag = RPMTAG_REQUIREVERSION;
 	flagtag = RPMTAG_REQUIREFLAGS;
-	extra = flag & _ALL_REQUIRES_MASK;
+	extra = depFlags & _ALL_REQUIRES_MASK;
     }
 
-    flag = (flag & (RPMSENSE_SENSEMASK | RPMSENSE_MULTILIB)) | extra;
+    depFlags = (depFlags & (RPMSENSE_SENSEMASK | RPMSENSE_MULTILIB)) | extra;
 
-    if (!version)
-	version = "";
+    if (depEVR == NULL)
+	depEVR = "";
     
     /* Check for duplicate dependencies. */
     if (headerGetEntry(h, nametag, NULL, (void **) &names, &len)) {
@@ -72,11 +71,11 @@ int addReqProv(/*@unused@*/ Spec spec, Header h,
 
 	while (len > 0) {
 	    len--;
-	    if (strcmp(names[len], name))
+	    if (strcmp(names[len], depName))
 		continue;
 	    if (flagtag && versions != NULL &&
-		(strcmp(versions[len], version) ||
-	((flags[len] | RPMSENSE_MULTILIB) != (flag | RPMSENSE_MULTILIB))))
+		(strcmp(versions[len], depEVR) ||
+	((flags[len] | RPMSENSE_MULTILIB) != (depFlags | RPMSENSE_MULTILIB))))
 		continue;
 	    if (indextag && indexes != NULL && indexes[len] != index)
 		continue;
@@ -84,7 +83,7 @@ int addReqProv(/*@unused@*/ Spec spec, Header h,
 	    /* This is a duplicate dependency. */
 	    duplicate = 1;
 
-	    if (flagtag && isDependsMULTILIB(flag) &&
+	    if (flagtag && isDependsMULTILIB(depFlags) &&
 		!isDependsMULTILIB(flags[len]))
 		    flags[len] |= RPMSENSE_MULTILIB;
 
@@ -97,12 +96,12 @@ int addReqProv(/*@unused@*/ Spec spec, Header h,
     }
 
     /* Add this dependency. */
-    headerAddOrAppendEntry(h, nametag, RPM_STRING_ARRAY_TYPE, &name, 1);
+    headerAddOrAppendEntry(h, nametag, RPM_STRING_ARRAY_TYPE, &depName, 1);
     if (flagtag) {
 	headerAddOrAppendEntry(h, versiontag,
-			       RPM_STRING_ARRAY_TYPE, &version, 1);
+			       RPM_STRING_ARRAY_TYPE, &depEVR, 1);
 	headerAddOrAppendEntry(h, flagtag,
-			       RPM_INT32_TYPE, &flag, 1);
+			       RPM_INT32_TYPE, &depFlags, 1);
     }
     if (indextag)
 	headerAddOrAppendEntry(h, indextag, RPM_INT32_TYPE, &index, 1);
diff --git a/build/rpmbuild.h b/build/rpmbuild.h
index 0fe7ef1ba..724a420e1 100644
--- a/build/rpmbuild.h
+++ b/build/rpmbuild.h
@@ -15,7 +15,7 @@
 /* but this will be needed */
 #include "rpmspec.h"
 
-/**
+/** \ingroup rpmbuild
  * Bit(s) to control buildSpec() operation.
  */
 typedef enum rpmBuildFlags_e {
@@ -32,8 +32,6 @@ typedef enum rpmBuildFlags_e {
     RPMBUILD_RMSPEC	= (1 << 10)	/*!< Remove spec file. */
 } rpmBuildFlags;
 
-/* from build/misc.h */
-
 #include <ctype.h>
 
 #define FREE(x) { if (x) free((void *)x); x = NULL; }
@@ -43,7 +41,7 @@ typedef enum rpmBuildFlags_e {
 #define PART_SUBNAME  0
 #define PART_NAME     1
 
-/**
+/** \ingroup rpmbuild
  * Spec file parser states.
  */
 typedef enum rpmParseState_e {
@@ -64,11 +62,10 @@ typedef enum rpmParseState_e {
     PART_TRIGGERUN	= 14,	/*!< */
     PART_VERIFYSCRIPT	= 15,	/*!< */
     PART_BUILDARCHITECTURES= 16,/*!< */
-    PART_TRIGGERPOSTUN	= 17	/*!< */
+    PART_TRIGGERPOSTUN	= 17,	/*!< */
+    PART_LAST		= 18	/*!< */
 } rpmParseState;
 
-/* from build/read.h */
-
 #define STRIP_NOTHING             0
 #define STRIP_TRAILINGSPACE (1 << 0)
 #define STRIP_COMMENTS      (1 << 1)
@@ -77,12 +74,12 @@ typedef enum rpmParseState_e {
 extern "C" {
 #endif
 
-/**
+/** \ingroup rpmbuild
  * Destroy uid/gid caches.
  */
 void freeNames(void);
 
-/**
+/** \ingroup rpmbuild
  * Return cached user name from user id.
  * @todo Implement using hash.
  * @param		user id
@@ -90,7 +87,7 @@ void freeNames(void);
  */
 /*@observer@*/ const char *getUname(uid_t uid);
 
-/**
+/** \ingroup rpmbuild
  * Return cached user name.
  * @todo Implement using hash.
  * @param		user name
@@ -98,7 +95,7 @@ void freeNames(void);
  */
 /*@observer@*/ const char *getUnameS(const char *uname);
 
-/**
+/** \ingroup rpmbuild
  * Return cached group name from group id.
  * @todo Implement using hash.
  * @param		group id
@@ -106,7 +103,7 @@ void freeNames(void);
  */
 /*@observer@*/ const char *getGname(gid_t gid);
 
-/**
+/** \ingroup rpmbuild
  * Return cached group name.
  * @todo Implement using hash.
  * @param		group name
@@ -114,156 +111,295 @@ void freeNames(void);
  */
 /*@observer@*/ const char *getGnameS(const char *gname);
 
-/**
+/** \ingroup rpmbuild
  * Return build hostname.
  * @return		build hostname
  */
 /*@observer@*/ const char *const buildHost(void);
 
-/**
+/** \ingroup rpmbuild
  * Return build time stamp.
  * @return		build time stamp
  */
 /*@observer@*/ time_t *const getBuildTime(void);
 
-/**
+/** \ingroup rpmbuild
+ * Read next line from spec file.
+ * @param spec		spec file control structure
+ * @param strip		truncate comments?
  * @return		0 on success, 1 on EOF, <0 on error
  */
 int readLine(Spec spec, int strip);
 
-/** */
+/** \ingroup rpmbuild
+ * Stop reading from spec file, freeing resources.
+ * @param spec		spec file control structure
+ */
 void closeSpec(Spec spec);
 
-/** */
+/** \ingroup rpmbuild
+ * Truncate comment lines.
+ * @param s		skip white space, truncate line at '#'
+ */
 void handleComments(char *s);
 
-/* from build/part.h */
-
-/**
+/** \ingroup rpmbuild
  * Check line for section separator, return next parser state.
  * @param		line from spec file
  * @return		next parser state
  */
 rpmParseState isPart(const char *line);
 
-/* from build/misc.h */
-
-/** */
+/** \ingroup rpmbuild
+ * Parse a number.
+ * @param		line from spec file
+ * @retval res		pointer to int
+ * @return		0 on success, 1 on failure
+ */
 int parseNum(const char *line, /*@out@*/int *res);
 
-/* from build/parse.h */
-
-/** */
+/** \ingroup rpmbuild
+ * Add changelog entry to header.
+ * @param h		header
+ * @param time		time of change
+ * @param name		person who made the change
+ * @param text		description of change
+ */
 void addChangelogEntry(Header h, time_t time, const char *name, const char *text);
 
-/**
+/** \ingroup rpmbuild
+ * Parse %%build/%%install/%%clean section(s) of a spec file.
+ * @param spec		spec file control structure
+ * @param parsePart	current rpmParseState
  * @return		>= 0 next rpmParseState, < 0 on error
  */
 int parseBuildInstallClean(Spec spec, rpmParseState parsePart);
 
-/**
+/** \ingroup rpmbuild
+ * Parse %%changelog section of a spec file.
+ * @param spec		spec file control structure
  * @return		>= 0 next rpmParseState, < 0 on error
  */
 int parseChangelog(Spec spec);
 
-/**
+/** \ingroup rpmbuild
+ * Parse %%description section of a spec file.
+ * @param spec		spec file control structure
  * @return		>= 0 next rpmParseState, < 0 on error
  */
 int parseDescription(Spec spec);
 
-/**
+/** \ingroup rpmbuild
+ * Parse %%files section of a spec file.
+ * @param spec		spec file control structure
  * @return		>= 0 next rpmParseState, < 0 on error
  */
 int parseFiles(Spec spec);
 
-/**
+/** \ingroup rpmbuild
+ * Parse tags from preamble of a spec file.
+ * @param spec		spec file control structure
+ * @param initialPackage
  * @return		>= 0 next rpmParseState, < 0 on error
  */
 int parsePreamble(Spec spec, int initialPackage);
 
-/**
+/** \ingroup rpmbuild
+ * Parse %%prep section of a spec file.
+ * @param spec		spec file control structure
  * @return		>= 0 next rpmParseState, < 0 on error
  */
 int parsePrep(Spec spec);
 
-/** */
+/** \ingroup rpmbuild
+ * Parse dependency relations from spec file and/or autogenerated output buffer.
+ * @param spec		spec file control structure
+ * @param pkg		package control structure
+ * @param field		text to parse (e.g. "foo < 0:1.2-3, bar = 5:6.7")
+ * @param tag		tag, identifies type of dependency
+ * @param index		(0 always)
+ * @param flags		dependency flags already known from context
+ * @return		0 on success, RPMERR_BADSPEC on failure
+ */
 int parseRCPOT(Spec spec, Package pkg, const char *field, int tag, int index,
 	       int flags);
 
-/**
+/** \ingroup rpmbuild
+ * Parse %%pre et al scriptlets from a spec file.
+ * @param spec		spec file control structure
+ * @param parsePart	current rpmParseState
  * @return		>= 0 next rpmParseState, < 0 on error
  */
 int parseScript(Spec spec, int parsePart);
 
-/** */
+/** \ingroup rpmbuild
+ * Parse %%trigger et al scriptlets from a spec file.
+ * @param spec		spec file control structure
+ * @param pkg		package control structure
+ * @param field
+ * @param tag
+ * @return
+ */
 int parseTrigger(Spec spec, Package pkg, char *field, int tag);
 
-/* from build/expression.h */
-
-/** */
-int parseExpressionBoolean(Spec, char *);
-
-/** */
-char *parseExpressionString(Spec, char *);
+/** \ingroup rpmbuild
+ * Evaluate boolean expression.
+ * @param spec		spec file control structure
+ * @param expr		expression to parse
+ * @return
+ */
+int parseExpressionBoolean(Spec spec, const char * expr);
 
-/* from build/build.h */
+/** \ingroup rpmbuild
+ * Evaluate string expression.
+ * @param spec		spec file control structure
+ * @param expr		expression to parse
+ * @return
+ */
+char *parseExpressionString(Spec spec, const char * expr);
 
-/** */
+/** \ingroup rpmbuild
+ * Run a build script, assembled from spec file scriptlet section.
+ *
+ * @param spec		spec file control structure
+ * @param what		type of script
+ * @param name		name of scriptlet section
+ * @param sb		lines that compose script body
+ * @param test		don't execute scripts or package if testing
+ * @return		0 on success, RPMERR_SCRIPT on failure
+ */
 int doScript(Spec spec, int what, const char *name, StringBuf sb, int test);
 
-/* from build/package.h */
-
-/** */
+/** \ingroup rpmbuild
+ * Find sub-package control structure by name.
+ * @param spec		spec file control structure
+ * @param name		(sub-)package name
+ * @param flag		if PART_SUBNAME, then 1st package name is prepended
+ * @retval pkg		package control structure
+ * @return		0 on success, 1 on failure
+ */
 int lookupPackage(Spec spec, const char *name, int flag, /*@out@*/Package *pkg);
 
-/** */
+/** \ingroup rpmbuild
+ * Create and initialize package control structure.
+ * @param spec		spec file control structure
+ * @return		package control structure
+ */
 /*@only@*/ Package newPackage(Spec spec);
 
-/** */
+/** \ingroup rpmbuild
+ * Destroy all packages associated with spec file.
+ * @param spec		spec file control structure
+ */
 void freePackages(Spec spec);
 
-/** */
-void freePackage(/*@only@*/ Package p);
-
-/* from build/reqprov.h */
+/** \ingroup rpmbuild
+ * Destroy package control structure.
+ * @param pkg		package control structure
+ */
+void freePackage(/*@only@*/ Package pkg);
 
-/** */
+/** \ingroup rpmbuild
+ * Add dependency to header, filtering duplicates.
+ * @param spec		spec file control structure
+ * @param h		header
+ * @param depFlags	(e.g. Requires: foo < 0:1.2-3, both "Requires:" and "<")
+ * @param depName	(e.g. Requires: foo < 0:1.2-3, "foo")
+ * @param depEVR	(e.g. Requires: foo < 0:1.2-3, "0:1.2-3")
+ * @param index		(0 always)
+ * @return		0 always
+ */
 int addReqProv(/*@unused@*/Spec spec, Header h,
-		int flag, const char *name, const char *version, int index);
+		int flag, const char *depName, const char *depEVR, int index);
 
-/** */
+/** \ingroup rpmbuild
+ * Add rpmlib feature dependency.
+ * @param h		header
+ * @param feature	rpm feature name (i.e. "rpmlib(Foo)" for feature Foo)
+ * @param featureEVR	rpm feature epoch/version/release
+ * @return		0 always
+ */
 int rpmlibNeedsFeature(Header h, const char * feature, const char * featureEVR);
 
-/* from build/files.h */
-
-/** */
+/** \ingroup rpmbuild
+ * Post-build processing for binary package(s).
+ * @param spec		spec file control structure
+ * @param installSpecialDoc
+ * @param test		don't execute scripts or package if testing
+ * @return		0 on success
+ */
 int processBinaryFiles(Spec spec, int installSpecialDoc, int test);
 
-/** */
+/** \ingroup rpmbuild
+ * Create and initialize header for source package.
+ * @param spec		spec file control structure
+ */
 void initSourceHeader(Spec spec);
 
-/** */
+/** \ingroup rpmbuild
+ * Post-build processing for source package.
+ * @param spec		spec file control structure
+ * @return		0 on success
+ */
 int processSourceFiles(Spec spec);
 
 /* global entry points */
 
-/** */
+/** \ingroup rpmbuild
+ * Parse spec file into spec control structure.
+ * @retval specp	spec file control structure
+ * @param specFile
+ * @param rootdir
+ * @param buildRoot
+ * @param inBuildArch
+ * @param passPhrase
+ * @param cookie
+ * @param anyarch
+ * @param force
+ * @return
+ */
 int parseSpec(Spec *specp, const char *specFile, const char *rootdir,
 		const char *buildRoot, int inBuildArch, const char *passPhrase,
 		char *cookie, int anyarch, int force);
 
-/** */
-extern int (*parseSpecVec) (Spec *specp, const char *specFile, const char *rootdir,
-		const char *buildRoot, int inBuildArch, const char *passPhrase,
+/** \ingroup rpmbuild
+ * @retval specp	spec file control structure
+ * @param specFile
+ * @param rootdir
+ * @param buildRoot
+ * @param inBuildArch
+ * @param passPhrase
+ * @param cookie
+ * @param anyarch
+ * @param force
+ * @return
+ */
+extern int (*parseSpecVec) (Spec *specp, const char *specFile,
+		const char *rootdir, const char *buildRoot,
+		int inBuildArch, const char *passPhrase,
 		char *cookie, int anyarch, int force);	/* XXX FIXME */
 
-/** */
+/** \ingroup rpmbuild
+ * Build stages state machine driver.
+ * @param spec		spec file control structure
+ * @param what		bit(s) to enable stages of build
+ * @param test		don't execute scripts or package if testing
+ * @return		0 on success
+ */
 int buildSpec(Spec spec, int what, int test);
 
-/** */
+/** \ingroup rpmbuild
+ * Generate binary package(s).
+ * @param spec		spec file control structure
+ * @return		0 on success
+ */
 int packageBinaries(Spec spec);
 
-/** */
+/** \ingroup rpmbuild
+ * Generate source package.
+ * @param spec		spec file control structure
+ * @return		0 on success
+ */
 int packageSources(Spec spec);
 
 #ifdef __cplusplus
diff --git a/build/rpmspec.h b/build/rpmspec.h
index e55aed2ed..8cd9956b8 100644
--- a/build/rpmspec.h
+++ b/build/rpmspec.h
@@ -6,13 +6,13 @@
  *  The Spec and Package data structures used during build.
  */
 
-/**
+/** \ingroup rpmbuild
  */
 typedef struct SpecStruct *Spec;
 
 #include "rpmmacro.h"
 
-/**
+/** \ingroup rpmbuild
  */
 struct TriggerFileEntry {
     int index;
@@ -29,7 +29,7 @@ struct TriggerFileEntry {
 
 #define RPMBUILD_DEFAULT_LANG "C"
 
-/**
+/** \ingroup rpmbuild
  */
 struct Source {
 /*@owned@*/ char *fullSource;
@@ -39,14 +39,14 @@ struct Source {
 /*@owned@*/ struct Source *next;
 };
 
-/**
+/** \ingroup rpmbuild
  */
 typedef struct ReadLevelEntry {
     int reading;
 /*@dependent@*/ struct ReadLevelEntry *next;
 } RLE_t;
 
-/**
+/** \ingroup rpmbuild
  */
 typedef struct OpenFileInfo {
 /*@only@*/ const char *fileName;
@@ -57,7 +57,7 @@ typedef struct OpenFileInfo {
 /*@owned@*/ struct OpenFileInfo *next;
 } OFI_t;
 
-/**
+/** \ingroup rpmbuild
  */
 struct spectag {
     int t_tag;
@@ -67,7 +67,7 @@ struct spectag {
 /*@only@*/ const char *t_msgid;
 };
 
-/**
+/** \ingroup rpmbuild
  */
 struct spectags {
 /*@owned@*/ struct spectag *st_t;
@@ -75,7 +75,7 @@ struct spectags {
     int st_ntags;
 };
 
-/**
+/** \ingroup rpmbuild
  */
 struct speclines {
 /*@only@*/ char **sl_lines;
@@ -83,7 +83,7 @@ struct speclines {
     int sl_nlines;
 };
 
-/**
+/** \ingroup rpmbuild
  * The structure used to store values parsed from a spec file.
  */
 struct SpecStruct {
@@ -138,7 +138,7 @@ struct SpecStruct {
 /*@owned@*/ struct PackageStruct *packages;	/*!< Package list. */
 };
 
-/**
+/** \ingroup rpmbuild
  * The structure used to store values for a package.
  */
 struct PackageStruct {
@@ -173,7 +173,7 @@ struct PackageStruct {
 /*@dependent@*/ struct PackageStruct *next;
 };
 
-/**
+/** \ingroup rpmbuild
  */
 typedef struct PackageStruct *Package;
 
@@ -181,31 +181,38 @@ typedef struct PackageStruct *Package;
 extern "C" {
 #endif
 
-/**
+/** \ingroup rpmbuild
+ * Create and initialize Spec structure.
  */
 /*@only@*/ Spec newSpec(void);
 
-/**
+/** \ingroup rpmbuild
+ * Destroy Spec structure.
+ * @param spec		spec file control structure
  */
 void freeSpec(/*@only@*/ Spec spec);
 
-/**
+/** \ingroup rpmbuild
+ * @param spec		spec file control structure
  */
 extern void (*freeSpecVec) (Spec spec);	/* XXX FIXME */
 
-/**
+/** \ingroup rpmbuild
  */
 struct OpenFileInfo * newOpenFileInfo(void);
 
-/**
+/** \ingroup rpmbuild
+ * @param spec		spec file control structure
  */
 struct spectag *stashSt(Spec spec, Header h, int tag, const char *lang);
 
-/**
+/** \ingroup rpmbuild
+ * @param spec		spec file control structure
  */
 int addSource(Spec spec, Package pkg, const char *field, int tag);
 
-/**
+/** \ingroup rpmbuild
+ * @param spec		spec file control structure
  */
 int parseNoSource(Spec spec, const char *field, int tag);
 
diff --git a/build/spec.c b/build/spec.c
index 52f6dc3e9..31cb3a72f 100644
--- a/build/spec.c
+++ b/build/spec.c
@@ -15,6 +15,8 @@ extern MacroContext rpmGlobalMacroContext;
 #define SKIPWHITE(_x)	{while(*(_x) && (isspace(*_x) || *(_x) == ',')) (_x)++;}
 #define SKIPNONWHITE(_x){while(*(_x) &&!(isspace(*_x) || *(_x) == ',')) (_x)++;}
 
+/**
+ */
 static inline void freeTriggerFiles(/*@only@*/ struct TriggerFileEntry *p)
 {
     struct TriggerFileEntry *o, *q = p;
@@ -29,6 +31,8 @@ static inline void freeTriggerFiles(/*@only@*/ struct TriggerFileEntry *p)
     }
 }
 
+/**
+ */
 static inline void freeCpioList(/*@only@*/ struct cpioFileMapping *cpioList, int cpioCount)
 {
     struct cpioFileMapping *p = cpioList;
@@ -43,6 +47,8 @@ static inline void freeCpioList(/*@only@*/ struct cpioFileMapping *cpioList, int
     FREE(cpioList);
 }
 
+/**
+ */
 static inline void freeSources(/*@only@*/ struct Source *s)
 {
     struct Source *r, *t = s;
@@ -55,7 +61,6 @@ static inline void freeSources(/*@only@*/ struct Source *s)
     }
 }
 
-/** */
 int lookupPackage(Spec spec, const char *name, int flag, /*@out@*/Package *pkg)
 {
     const char *pname;
@@ -95,7 +100,6 @@ int lookupPackage(Spec spec, const char *name, int flag, /*@out@*/Package *pkg)
     return ((p == NULL) ? 1 : 0);
 }
 
-/** */
 Package newPackage(Spec spec)
 {
     Package p;
@@ -144,7 +148,6 @@ Package newPackage(Spec spec)
     return p;
 }
 
-/** */
 void freePackage(/*@only@*/ Package p)
 {
     if (p == NULL)
@@ -170,7 +173,6 @@ void freePackage(/*@only@*/ Package p)
     free(p);
 }
 
-/** */
 void freePackages(Spec spec)
 {
     Package p;
@@ -182,6 +184,8 @@ void freePackages(Spec spec)
     }
 }
 
+/**
+ */
 static inline /*@owned@*/ struct Source *findSource(Spec spec, int num, int flag)
 {
     struct Source *p;
@@ -195,28 +199,6 @@ static inline /*@owned@*/ struct Source *findSource(Spec spec, int num, int flag
     return NULL;
 }
 
-#ifdef	UNUSED
-static char *getSourceAux(Spec spec, int num, int flag, int full)
-{
-    struct Source *p = spec->sources;
-
-    p = findSource(spec, num, flag);
-
-    return (p) ? (full ? p->fullSource : p->source) : NULL;
-}
-
-static char *getSource(Spec spec, int num, int flag)
-{
-    return getSourceAux(spec, num, flag, 0);
-}
-
-static char *getFullSource(Spec spec, int num, int flag)
-{
-    return getSourceAux(spec, num, flag, 1);
-}
-#endif	/* UNUSED */
-
-/** */
 int parseNoSource(Spec spec, const char *field, int tag)
 {
     const char *f, *fe;
@@ -261,7 +243,6 @@ int parseNoSource(Spec spec, const char *field, int tag)
     return 0;
 }
 
-/** */
 int addSource(Spec spec, Package pkg, const char *field, int tag)
 {
     struct Source *p;
@@ -352,6 +333,8 @@ int addSource(Spec spec, Package pkg, const char *field, int tag)
     return 0;
 }
 
+/**
+ */
 static inline struct speclines * newSl(void)
 {
     struct speclines *sl = NULL;
@@ -364,6 +347,8 @@ static inline struct speclines * newSl(void)
     return sl;
 }
 
+/**
+ */
 static inline void freeSl(/*@only@*/struct speclines *sl)
 {
     int i;
@@ -375,6 +360,8 @@ static inline void freeSl(/*@only@*/struct speclines *sl)
     free(sl);
 }
 
+/**
+ */
 static inline struct spectags * newSt(void)
 {
     struct spectags *st = NULL;
@@ -387,6 +374,8 @@ static inline struct spectags * newSt(void)
     return st;
 }
 
+/**
+ */
 static inline void freeSt(/*@only@*/struct spectags *st)
 {
     int i;
@@ -401,7 +390,6 @@ static inline void freeSt(/*@only@*/struct spectags *st)
     free(st);
 }
 
-/** */
 Spec newSpec(void)
 {
     Spec spec;
@@ -462,7 +450,6 @@ Spec newSpec(void)
     return spec;
 }
 
-/** */
 void freeSpec(/*@only@*/ Spec spec)
 {
     struct OpenFileInfo *ofi;
@@ -527,7 +514,6 @@ void freeSpec(/*@only@*/ Spec spec)
     free(spec);
 }
 
-/** */
 /*@only@*/ struct OpenFileInfo * newOpenFileInfo(void)
 {
     struct OpenFileInfo *ofi;