doxygen annotations.

CVS patchset: 4105
CVS date: 2000/08/23 13:02:13

5 files changed, 179 insertions, 42 deletions

diff --git a/lib/install.c b/lib/install.c
index 1a66e5a78..2b8092e79 100644
--- a/lib/install.c
+++ b/lib/install.c
@@ -9,6 +9,9 @@
 #include "misc.h"
 #include <assert.h>
 
+/**
+ * Private data for cpio callback.
+ */
 struct callbackInfo {
     unsigned long archiveSize;
     rpmCallbackFunction notify;
@@ -38,9 +41,12 @@ struct fileInfo {
 } ;
 
 /* XXX add more tags */
+/**
+ * Macros to be defined from per-header tag values.
+ */
 static struct tagMacro {
-	const char *	macroname;
-	int		tag;
+	const char *	macroname;	/*!< Macro name to define. */
+	int		tag;		/*!< Header tag to use for value. */
 } tagMacros[] = {
 	{ "name",	RPMTAG_NAME },
 	{ "version",	RPMTAG_VERSION },
@@ -51,7 +57,11 @@ static struct tagMacro {
 	{ NULL, 0 }
 };
 
-/** */
+/**
+ * Define per-header macros.
+ * @param h		header
+ * @return		0 always
+ */
 static int rpmInstallLoadMacros(Header h)
 {
     struct tagMacro *tagm;
@@ -78,7 +88,8 @@ static int rpmInstallLoadMacros(Header h)
     return 0;
 }
 
-/** */
+/**
+ */
 static /*@only@*/ struct fileMemory *newFileMemory(void)
 {
     struct fileMemory *fileMem = xmalloc(sizeof(*fileMem));
@@ -88,7 +99,8 @@ static /*@only@*/ struct fileMemory *newFileMemory(void)
     return fileMem;
 }
 
-/** */
+/**
+ */
 static void freeFileMemory( /*@only@*/ struct fileMemory *fileMem)
 {
     if (fileMem->files) free(fileMem->files);
@@ -98,7 +110,10 @@ static void freeFileMemory( /*@only@*/ struct fileMemory *fileMem)
 }
 
 /* files should not be preallocated */
-/** */
+/**
+ * @param h		header
+ * @retval		0 always
+ */
 static int assembleFileList(Header h, /*@out@*/ struct fileMemory ** memPtr,
 	 /*@out@*/ int * fileCountPtr, /*@out@*/ struct fileInfo ** filesPtr,
 	 int stripPrefixLength, enum fileActions * actions)
@@ -153,7 +168,9 @@ static int assembleFileList(Header h, /*@out@*/ struct fileMemory ** memPtr,
     return 0;
 }
 
-/** */
+/**
+ * @param h		header
+ */
 static void setFileOwners(Header h, struct fileInfo * files, int fileCount)
 {
     char ** fileOwners;
@@ -185,7 +202,11 @@ static void setFileOwners(Header h, struct fileInfo * files, int fileCount)
     free(fileGroups);
 }
 
-/** */
+/**
+ * Truncate header changelog tag to configurable limit before installing.
+ * @param h		header
+ * @return		none
+ */
 static void trimChangelog(Header h)
 {
     int * times;
@@ -236,7 +257,9 @@ static void trimChangelog(Header h)
     free(texts);
 }
 
-/** */
+/**
+ * @param h		header
+ */
 static int mergeFiles(Header h, Header newH, enum fileActions * actions)
 {
     int i, j, k, fileCount;
@@ -493,7 +516,9 @@ static void callback(struct cpioCallbackInfo * cpioInfo, void * data)
 }
 
 /* NULL files means install all files */
-/** */
+/**
+ * @param h		header
+ */
 static int installArchive(FD_t fd, struct fileInfo * files,
 			  int fileCount, rpmCallbackFunction notify,
 			  void * notifyData, const void * pkgKey, Header h,
@@ -601,10 +626,10 @@ static int installArchive(FD_t fd, struct fileInfo * files,
     return rc;
 }
 
-/* 0 success */
-/* 1 bad magic */
-/* 2 error */
-/** */
+/**
+ * @param h		header
+ * @return		0 on success, 1 on bad magic, 2 on error
+ */
 static int installSources(Header h, const char * rootdir, FD_t fd,
 			  const char ** specFilePtr, rpmCallbackFunction notify,
 			  void * notifyData)
@@ -848,9 +873,6 @@ const char *const fileActionString(enum fileActions a)
     return "???";
 }
 
-/* 0 success */
-/* 1 bad magic */
-/* 2 error */
 int rpmInstallSourcePackage(const char * rootdir, FD_t fd,
 			    const char ** specFile, rpmCallbackFunction notify,
 			    void * notifyData, char ** cookie)
@@ -884,9 +906,6 @@ int rpmInstallSourcePackage(const char * rootdir, FD_t fd,
     return rc;
 }
 
-/* 0 success */
-/* 1 bad magic */
-/* 2 error */
 int installBinaryPackage(const char * rootdir, rpmdb db, FD_t fd, Header h,
 		         int flags, rpmCallbackFunction notify,
 			 void * notifyData, const void * pkgKey,
diff --git a/lib/install.h b/lib/install.h
index 8f6197d5e..33d3132d3 100644
--- a/lib/install.h
+++ b/lib/install.h
@@ -3,12 +3,16 @@
 
 #include <rpmlib.h>
 
+/**
+ */
 struct sharedFile {
     int mainFileNumber;
     int secRecOffset;
     int secFileNumber;
 } ;
 
+/**
+ */
 struct sharedFileInfo {
     int pkgFileNum;
     int otherFileNum;
@@ -16,40 +20,107 @@ struct sharedFileInfo {
     int isRemoved;
 };
 
+/**
+ */
 enum fileActions { FA_UNKNOWN = 0, FA_CREATE, FA_BACKUP, FA_SAVE, FA_SKIP, 
 		   FA_ALTNAME, FA_REMOVE, FA_SKIPNSTATE, FA_SKIPNETSHARED,
 		   FA_SKIPMULTILIB };
+
+/**
+ */
 enum fileTypes { XDIR, BDEV, CDEV, SOCK, PIPE, REG, LINK } ;
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/**
+ * @param prefix	path to top of install tree
+ * @param h		header
+ * @param scriptTag
+ * @param progTag
+ * @param arg
+ * @param norunScripts
+ * @param err		stderr file handle
+ */
 int runInstScript(const char * prefix, Header h, int scriptTag, int progTag,
 		int arg, int norunScripts, FD_t err);
-/* this looks for triggers in the database which h would set off */
-int runTriggers(const char * root, rpmdb db, int sense, Header h,
+
+/**
+ * Run trigger scripts in the database that are fired by header.
+ * @param root		path to top of install tree
+ * @param rpmdb		rpm database
+ * @param sense
+ * @param h		header
+ * @param countCorrection
+ * @param scriptFd
+ */
+int runTriggers(const char * root, rpmdb rpmdb, int sense, Header h,
 		int countCorrection, FD_t scriptFd);
+
 /* while this looks for triggers in h which are set off by things in the db
    database to calculate arguments to the trigger */
-int runImmedTriggers(const char * root, rpmdb db, int sense, Header h,
+/**
+ * @param root		path to top of install tree
+ * @param rpmdb		rpm database
+ * @param sense
+ * @param h		header
+ * @param countCorrection
+ * @param scriptFd
+ */
+int runImmedTriggers(const char * root, rpmdb rpmdb, int sense, Header h,
 		int countCorrection, FD_t scriptFd);
 
+/**
+ * Return formatted string representation of file disposition.
+ * @param a		file dispostion
+ * @return		formatted string
+ */
 /*@observer@*/ const char *const fileActionString(enum fileActions a);
 
-int installBinaryPackage(const char * rootdir, rpmdb db, FD_t fd, Header h,
+/**
+ * Install binary package (from transaction set).
+ * @param rootdir	path to top of install tree
+ * @param rpmdb		rpm database
+ * @param fd		package file handle
+ * @param h		package header
+ * @param flags		transaction flags
+ * @param notify	progress callback
+ * @param notifyData	progress callback private data
+ * @param pkgKey	package private data
+ * @param actions	array of file dispositions
+ * @param sharedList	header instances of packages that share files
+ * @param scriptFd
+ * @return		0 on success, 1 on bad magic, 2 on error
+ */
+int installBinaryPackage(const char * rootdir, rpmdb rpmdb, FD_t fd, Header h,
 		int flags, rpmCallbackFunction notify, 
 		void * notifyData, const void * pkgKey, 
 		enum fileActions * actions,
 		struct sharedFileInfo * sharedList, FD_t scriptFd);
-int removeBinaryPackage(const char * root, rpmdb db, unsigned int offset,
+
+/**
+ * Erase binary package (from transaction set).
+ * @param rootdir	path to top of install tree
+ * @param rpmdb		rpm database
+ * @param fd		package file handle
+ * @param offset	header instance in rpm database
+ * @param h		package header
+ * @param flags		transaction flags
+ * @param notify	progress callback
+ * @param notifyData	progress callback private data
+ * @param pkgKey	package private data
+ * @param actions	array of file dispositions
+ * @param scriptFd
+ * @return
+ */
+int removeBinaryPackage(const char * rootdir, rpmdb rpmdb, unsigned int offset,
 		Header h,
 		int flags, rpmCallbackFunction notify, 
 		void * notifyData, const void * pkgKey, 
 		enum fileActions * actions,
 		FD_t scriptFd);
 
-
 #ifdef __cplusplus
 }
 #endif
diff --git a/lib/misc.c b/lib/misc.c
index 278ff0196..040b279d5 100644
--- a/lib/misc.c
+++ b/lib/misc.c
@@ -675,7 +675,7 @@ int rpmHeaderGetEntry(Header h, int_32 tag, int_32 *type,
 /*
  * XXX Yet Another dressed entry to unify signature/header tag retrieval.
  */
-int rpmPackageGetEntry(void *leadp, Header sigs, Header h,
+int rpmPackageGetEntry( /*@unused@*/ void *leadp, Header sigs, Header h,
 	int_32 tag, int_32 *type, void **p, int_32 *c)
 {
     int_32 sigtag;
diff --git a/lib/misc.h b/lib/misc.h
index a253e38e8..dda1035bc 100644
--- a/lib/misc.h
+++ b/lib/misc.h
@@ -11,31 +11,80 @@
 extern "C" {
 #endif
 
+/**
+ */
 /*@only@*/ char ** splitString(const char * str, int length, char sep);
+
+/**
+ */
 void	freeSplitString( /*@only@*/ char ** list);
-void	stripTrailingSlashes(char * str);
 
+/**
+ */
+void	stripTrailingSlashes(char * str)	/*@modifies *str @*/;
+
+/**
+ */
+int	rpmfileexists(const char * filespec)	/*@*/;
+
+/**
+ */
 int	rpmfileexists(const char * filespec);
 
+/**
+ */
 int	rpmvercmp(const char * one, const char * two);
 
 /* these are like the normal functions, but they malloc() the space which
    is needed */
+
+/**
+ */
+int	rpmfileexists(const char * filespec);
+
+/**
+ */
 int	dosetenv(const char *name, const char *value, int overwrite);
+
+/**
+ */
 int	doputenv(const char * str);
 
+/**
+ */
 int	makeTempFile(const char * prefix, /*@out@*/ const char ** fnptr,
 			/*@out@*/ FD_t * fdptr);
-char *	currentDirectory(void);		/* result needs to be freed */
+
+/**
+ * @return		cureent working directory (malloc'ed)
+ */
+/*@only@*/ char * currentDirectory(void);
+
+/**
+ */
 void	compressFilelist(Header h);
+
+/**
+ */
 void	expandFilelist(Header h);
+
+/**
+ */
 void	buildOrigFileList(Header h, /*@out@*/ const char *** fileListPtr, 
 			/*@out@*/ int * fileCountPtr);
 
-int myGlobPatternP (const char *patternURL);
+/**
+ */
+int myGlobPatternP (const char *patternURL)	/*@*/;
+
+/**
+ */
 int rpmGlob(const char * patterns, /*@out@*/ int * argcPtr,
-			/*@out@*/ const char *** argvPtr);
+	/*@out@*/ const char *** argvPtr)
+		/*@modifies *argcPtr, *argvPtr @*/;
 
+/**
+ */
 void providePackageNVR(Header h);
 
 #ifdef __cplusplus
diff --git a/lib/package.c b/lib/package.c
index 4414e4857..ec2ba8022 100644
--- a/lib/package.c
+++ b/lib/package.c
@@ -15,18 +15,22 @@
 #include "rpmlead.h"
 #include "signature.h"
 
-/* 0 = success */
-/* 1 = bad magic */
-/* 2 = error */
+/**
+ * Retrieve package components from file handle.
+ * @param fd		file handle
+ * @param leadPtr	address of lead (or NULL)
+ * @param sigs		address of signatures (or NULL)
+ * @param hdrPtr	address of header (or NULL)
+ * @return		0 on success, 1 on bad magic, 2 on error
+ */
 static int readPackageHeaders(FD_t fd, /*@out@*/struct rpmlead * leadPtr, 
 			      /*@out@*/Header * sigs, /*@out@*/Header * hdrPtr)
+	/*@modifies *leadPtr, *sigs, *hdrPtr @*/
 {
     Header hdrBlock;
     struct rpmlead leadBlock;
     Header * hdr = NULL;
     struct rpmlead * lead;
-    int_8 arch;
-    int isSource;
     char * defaultPrefix;
     struct stat sb;
     int_32 true = 1;
@@ -122,17 +126,11 @@ static int readPackageHeaders(FD_t fd, /*@out@*/struct rpmlead * leadPtr,
     return 0;
 }
 
-/* 0 = success */
-/* 1 = bad magic */
-/* 2 = error */
 int rpmReadPackageInfo(FD_t fd, Header * signatures, Header * hdr)
 {
     return readPackageHeaders(fd, NULL, signatures, hdr);
 }
 
-/* 0 = success */
-/* 1 = bad magic */
-/* 2 = error */
 int rpmReadPackageHeader(FD_t fd, Header * hdr, int * isSource, int * major,
 		  int * minor)
 {