Doxygen annotations.

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

diff --git a/rpmio/macro.c b/rpmio/macro.c
index 8d75813..254f1d3 100644 (file)
--- 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 5853758..a508eee 100644 (file)
--- 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 a15a26c..8ddb3d8 100644 (file)
--- 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 e80bbcf..453e1b3 100644 (file)
--- 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 afe7a95..01c34a3 100644 (file)
--- 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 7f261e4..7ec6374 100644 (file)
--- 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 166c843..a5275f9 100644 (file)
--- 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 6a26afe..b8c6688 100644 (file)
--- 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 e9c0577..0670db1 100644 (file)
--- 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 b4b4f1d..5c878be 100644 (file)
--- 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 67f2d1c..545c5a7 100644 (file)
--- 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 bf69c15..60a27fd 100644 (file)
--- 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 bb7c2d9..e0379d6 100644 (file)
--- 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 ccb602e..7dfa68d 100644 (file)
--- 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 04a7e14..c00c136 100644 (file)
--- 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 0400f93..d815304 100644 (file)
--- 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 6374757..5a264b4 100644 (file)
--- 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;