Doxygen annotations.

CVS patchset: 4129
CVS date: 2000/08/27 18:34:02

17 files changed, 145 insertions, 23 deletions

diff --git a/rpmio/macro.c b/rpmio/macro.c
index 8d7581391..254f1d33f 100644
--- a/rpmio/macro.c
+++ b/rpmio/macro.c
@@ -1,5 +1,10 @@
 #include "system.h"
 
+/** \ingroup rpmrc rpmio
+ * \file rpmio/macro.c
+ *
+ */
+
 static int _debug = 0;
 
 #include <assert.h>
diff --git a/rpmio/messages.c b/rpmio/messages.c
index 5853758b3..a508eeeea 100644
--- a/rpmio/messages.c
+++ b/rpmio/messages.c
@@ -1,5 +1,9 @@
 #include "system.h"
 
+/** \ingroup rpmio
+ * \file rpmio/messages.c
+ */
+
 #include <stdarg.h>
 
 #include <rpmmessages.h>
diff --git a/rpmio/rpmerr.c b/rpmio/rpmerr.c
index a15a26c92..8ddb3d8b3 100644
--- a/rpmio/rpmerr.c
+++ b/rpmio/rpmerr.c
@@ -1,5 +1,9 @@
 #include "system.h"
 
+/** \ingroup rpmio
+ * \file rpmio/rpmerr.c
+ */
+
 #include <stdarg.h>
 
 #include <rpmerr.h>
diff --git a/rpmio/rpmerr.h b/rpmio/rpmerr.h
index e80bbcff9..453e1b38f 100644
--- a/rpmio/rpmerr.h
+++ b/rpmio/rpmerr.h
@@ -1,6 +1,10 @@
 #ifndef H_RPMERR
 #define H_RPMERR
 
+/** \ingroup rpmio
+ * \file rpmio/rpmerr.h
+ */
+
 #define	RPMERR_GDBMOPEN		-2      /* gdbm open failed */
 #define	RPMERR_GDBMREAD		-3	/* gdbm read failed */
 #define	RPMERR_GDBMWRITE	-4	/* gdbm write failed */
diff --git a/rpmio/rpmio.c b/rpmio/rpmio.c
index afe7a9531..01c34a3ec 100644
--- a/rpmio/rpmio.c
+++ b/rpmio/rpmio.c
@@ -1,5 +1,9 @@
 #include "system.h"
 
+/** \ingroup rpmio
+ * \file rpmio/rpmio.c
+ */
+
 #include <stdarg.h>
 
 #ifdef	__LCLINT__
diff --git a/rpmio/rpmio.h b/rpmio/rpmio.h
index 7f261e438..7ec637483 100644
--- a/rpmio/rpmio.h
+++ b/rpmio/rpmio.h
@@ -1,6 +1,11 @@
 #ifndef	H_RPMIO
 #define	H_RPMIO
 
+/** \ingroup rpmio
+ * \file rpmio/rpmio.h
+ *
+ */
+
 #include <sys/types.h>
 #include <sys/stat.h>
 #include <dirent.h>
diff --git a/rpmio/rpmio_api.c b/rpmio/rpmio_api.c
index 166c843fd..a5275f938 100644
--- a/rpmio/rpmio_api.c
+++ b/rpmio/rpmio_api.c
@@ -1,3 +1,7 @@
+/** \ingroup rpmio
+ * \file rpmio/rpmio_api.c
+ */
+
 #include "system.h"
 
 /* XXX rename the static inline version of fdFileno */
diff --git a/rpmio/rpmio_internal.h b/rpmio/rpmio_internal.h
index 6a26afef5..b8c66883e 100644
--- a/rpmio/rpmio_internal.h
+++ b/rpmio/rpmio_internal.h
@@ -1,6 +1,10 @@
 #ifndef	H_RPMIO_INTERNAL
 #define	H_RPMIO_INTERNAL
 
+/** \ingroup rpmio
+ * \file rpmio/rpmio_internal.h
+ */
+
 static inline int fdFileno(void * cookie);
 
 #include <rpmio.h>
diff --git a/rpmio/rpmmacro.h b/rpmio/rpmmacro.h
index e9c05777f..0670db152 100644
--- a/rpmio/rpmmacro.h
+++ b/rpmio/rpmmacro.h
@@ -1,6 +1,10 @@
 #ifndef _H_MACRO_
 #define	_H_MACRO_
 
+/** \ingroup rpmio
+ * \file rpmio/rpmmacro.h
+ */
+
 /*! The structure used to store a macro. */
 typedef /*@abstract@*/ struct MacroEntry {
 	struct MacroEntry *prev;/*!< Macro entry stack. */
diff --git a/rpmio/rpmmalloc.c b/rpmio/rpmmalloc.c
index b4b4f1db9..5c878be2e 100644
--- a/rpmio/rpmmalloc.c
+++ b/rpmio/rpmmalloc.c
@@ -1,3 +1,7 @@
+/** \ingroup rpmio
+ * \file rpmio/rpmmalloc.c
+ */
+
 #include "system.h"
 
 #if !defined(EXIT_FAILURE)
diff --git a/rpmio/rpmmessages.h b/rpmio/rpmmessages.h
index 67f2d1cc9..545c5a70f 100644
--- a/rpmio/rpmmessages.h
+++ b/rpmio/rpmmessages.h
@@ -1,6 +1,10 @@
 #ifndef H_RPMMESSAGES
 #define H_RPMMESSAGES
 
+/** \ingroup rpmio
+ * \file rpmio/rpmmessages.h
+ */
+
 #define	RPMMESS_DEBUG      1
 #define	RPMMESS_VERBOSE    2
 #define	RPMMESS_NORMAL     3
diff --git a/rpmio/rpmrpc.c b/rpmio/rpmrpc.c
index bf69c154c..60a27fdc3 100644
--- a/rpmio/rpmrpc.c
+++ b/rpmio/rpmrpc.c
@@ -1,3 +1,7 @@
+/** \ingroup rpmio
+ * \file rpmio/rpmrpc.c
+ */
+
 #include "system.h"
 
 #include <rpmio_internal.h>
diff --git a/rpmio/rpmurl.h b/rpmio/rpmurl.h
index bb7c2d979..e0379d696 100644
--- a/rpmio/rpmurl.h
+++ b/rpmio/rpmurl.h
@@ -1,37 +1,47 @@
 #ifndef H_RPMURL
 #define H_RPMURL
 
+/** \ingroup rpmio
+ * \file rpmio/rpmurl.h
+ */
+
 #include <assert.h>
 
+/**
+ * Supported URL types.
+ */
 typedef enum {
-    URL_IS_UNKNOWN	= 0,
-    URL_IS_DASH		= 1,
-    URL_IS_PATH		= 2,
-    URL_IS_FTP		= 3,
-    URL_IS_HTTP		= 4
+    URL_IS_UNKNOWN	= 0,	/*!< unknown (aka a file) */
+    URL_IS_DASH		= 1,	/*!< stdin/stdout */
+    URL_IS_PATH		= 2,	/*!< file://... */
+    URL_IS_FTP		= 3,	/*!< ftp://... */
+    URL_IS_HTTP		= 4	/*!< http://... */
 } urltype;
 
 #define	URLMAGIC	0xd00b1ed0
 #define	URLSANE(u)	assert(u && u->magic == URLMAGIC)
 
+/**
+ * URL control structure.
+ */
 typedef /*@abstract@*/ /*@refcounted@*/ struct urlinfo {
-/*@refs@*/ int nrefs;
-    const char * url;		/* copy of original url */
+/*@refs@*/ int nrefs;		/*!< no. of references */
+    const char * url;		/*!< copy of original url */
     const char * service;
     const char * user;
     const char * password;
     const char * host;
     const char * portstr;
-    const char * proxyu;	/* FTP: proxy user */
-    const char * proxyh;	/* FTP/HTTP: proxy host */
-    int proxyp;			/* FTP/HTTP: proxy port */
+    const char * proxyu;	/*!< FTP: proxy user */
+    const char * proxyh;	/*!< FTP/HTTP: proxy host */
+    int proxyp;			/*!< FTP/HTTP: proxy port */
     int	port;
     int urltype;
-    FD_t ctrl;			/* control channel */
-    FD_t data;			/* per-xfer data channel */
-    int bufAlloced;		/* sizeof I/O buffer */
-    char *buf;			/* I/O buffer */
-    int openError;		/* Type of open failure */
+    FD_t ctrl;			/*!< control channel */
+    FD_t data;			/*!< per-xfer data channel */
+    int bufAlloced;		/*!< sizeof I/O buffer */
+    char *buf;			/*!< I/O buffer */
+    int openError;		/*!< Type of open failure */
     int httpVersion;
     int httpHasRange;
     int magic;
@@ -43,24 +53,70 @@ extern "C" {
 
 extern int url_iobuf_size;
 
-urlinfo	urlLink(urlinfo u, const char * msg);
-urlinfo	XurlLink(urlinfo u, const char * msg, const char * file, unsigned line);
-#define	urlLink(_u, _msg) XurlLink(_u, _msg, __FILE__, __LINE__)
-
+/**
+ * Create a URL control structure instance.
+ * @param msg		debugging identifier (unused)
+ * @return		new instance
+ */
 urlinfo	urlNew(const char * msg);
 urlinfo	XurlNew(const char * msg, const char * file, unsigned line);
 #define	urlNew(_msg) XurlNew(_msg, __FILE__, __LINE__)
 
+/**
+ * Reference a URL control structure instance.
+ * @param u		URL control structure
+ * @param msg		debugging identifier (unused)
+ * @return		referenced instance
+ */
+urlinfo	urlLink(urlinfo u, const char * msg);
+urlinfo	XurlLink(urlinfo u, const char * msg, const char * file, unsigned line);
+#define	urlLink(_u, _msg) XurlLink(_u, _msg, __FILE__, __LINE__)
+
+/**
+ * Dereference a URL control structure instance.
+ * @param u		URL control structure
+ * @param msg		debugging identifier (unused)
+ * @return		dereferenced instance (NULL if freed)
+ */
 urlinfo	urlFree( /*@killref@*/ urlinfo u, const char * msg);
 urlinfo	XurlFree( /*@killref@*/ urlinfo u, const char * msg, const char * file, unsigned line);
 #define	urlFree(_u, _msg) XurlFree(_u, _msg, __FILE__, __LINE__)
 
+/**
+ * Free cached URL control structures.
+ */
 void	urlFreeCache(void);
 
-urltype	urlIsURL(const char * url);
-int	urlPath(const char * url, /*@out@*/ const char ** pathp);
-int 	urlSplit(const char * url, /*@out@*/ urlinfo * u);
+/**
+ * Return type of URL.
+ * @param url		url string
+ * @return		type of url
+ */
+urltype	urlIsURL(const char * url)	/*@*/;
+
+/**
+ * Return path component of URL.
+ * @param url		url string
+ * @retval pathp	pointer to path component of url
+ * @return		type of url
+ */
+urltype	urlPath(const char * url, /*@out@*/ const char ** pathp)	/*@*/;
+
+/**
+ * Parse URL string into a control structure.
+ * @param url		url string
+ * @retval u		address of new control instance pointer
+ * @return		0 on success, -1 on error
+ */
+int 	urlSplit(const char * url, /*@out@*/ urlinfo * u)
+		/*@modifies *u @*/;
 
+/**
+ * Copy data from URL to local file.
+ * @param url		url string of source
+ * @param dest		file name of destination
+ * @return		0 on success, otherwise FTPERR_* code
+ */
 int	urlGetFile(const char * url, const char * dest);
 
 #ifdef __cplusplus
diff --git a/rpmio/trpmio.c b/rpmio/trpmio.c
index ccb602e10..7dfa68d60 100644
--- a/rpmio/trpmio.c
+++ b/rpmio/trpmio.c
@@ -1,3 +1,7 @@
+/** \ingroup rpmio
+ * \file rpmio/trpmio.c
+ */
+
 #include <stdio.h>
  
 #include "rpmio.h"
diff --git a/rpmio/ugid.c b/rpmio/ugid.c
index 04a7e14bb..c00c136f4 100644
--- a/rpmio/ugid.c
+++ b/rpmio/ugid.c
@@ -1,3 +1,7 @@
+/** \ingroup rpmio
+ * \file rpmio/ugid.c
+ */
+
 #include "system.h"
 
 #include "ugid.h"
diff --git a/rpmio/ugid.h b/rpmio/ugid.h
index 0400f934a..d81530433 100644
--- a/rpmio/ugid.h
+++ b/rpmio/ugid.h
@@ -1,6 +1,10 @@
 #ifndef H_UGID
 #define H_UGID
 
+/** \ingroup rpmio
+ * \file rpmio/ugid.h
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
diff --git a/rpmio/url.c b/rpmio/url.c
index 6374757a8..5a264b4ba 100644
--- a/rpmio/url.c
+++ b/rpmio/url.c
@@ -1,3 +1,7 @@
+/** \ingroup rpmio
+ * \file rpmio/url.c
+ */
+
 #include "system.h"
 
 #ifdef	__LCLINT__
@@ -306,7 +310,7 @@ urltype urlIsURL(const char * url) {
 }
 
 /* Return path portion of url (or pointer to NUL if url == NULL) */
-int urlPath(const char * url, const char ** pathp)
+urltype urlPath(const char * url, const char ** pathp)
 {
     const char *path;
     int urltype;