apr-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ian Holsman <i...@cnet.com>
Subject [PATCH] Doxygen'ization of apr_file_info/apr_pool/apr_errno/apr
Date Sat, 11 Aug 2001 05:12:13 GMT
The following patch is a start/continuation of moving the documentation
over to Doxygen.
This is the first patch in several (all APR include files have to be done)
The main highlight is that it Groups functions in functional 
groups/subgroups.

    * APR Functions <http://localhost/dox/group__APR.html>
          * Error Codes
            <http://localhost/dox/group__APR__Error__Codes.html>
          * File Handling Functions
            <http://localhost/dox/group__APR__File__Handle.html>
                * File Permissions flags
                  <http://localhost/dox/group__APR__file__handle__permission.html>

                * Stat Functions
                  <http://localhost/dox/group__APR__File__Info.html>
                * Directory Manipulation Functions
                  <http://localhost/dox/group__APR__DIRECTORY.html>
                * FilePath Manipulation operations
                  <http://localhost/dox/group__apr__filepath.html>
          * Pool Allocation Functions
            <http://localhost/dox/group__APR__Pool.html>
                * Pool Debugging functions.
                  <http://localhost/dox/group__PoolDebug.html>

If this is accepted, I'll start converting other ones over soon.
existing Doxygen output can be viewed at http://docx.webperf.org

..Ian
----8<------Patch begin
Index: apr_errno.h
===================================================================
RCS file: /home/cvspublic/apr/include/apr_errno.h,v
retrieving revision 1.77
diff -u -r1.77 apr_errno.h
--- apr_errno.h    2001/08/07 23:22:52    1.77
+++ apr_errno.h    2001/08/11 04:59:40
@@ -69,6 +69,11 @@
  * @file apr_errno.h
  * @brief Error Codes
  */
+/**
+ * @defgroup APR_Error_Codes Error Codes
+ * @ingroup APR
+ * @{
+ */
 
 /**
  * Type for specifying an error or status code.
@@ -80,32 +85,33 @@
  * @param statcode The error code the get a string for.
  * @param buf A buffer to hold the error string.
  * @param bufsize Size of the buffer to hold the string.
- * @deffunc char *apr_strerror(apr_status_t statcode, char *buf, 
apr_size_t bufsize)
  */
 APR_DECLARE(char *) apr_strerror(apr_status_t statcode, char *buf,
                                  apr_size_t bufsize);
 
 /**
+ * @def APR_FROM_OS_ERROR(os_err_type syserr)
  * Fold a platform specific error into an apr_status_t code.
+ * @return apr_status_t
  * @param syserr The platform os error code.
- * @deffunc apr_status_t APR_FROM_OS_ERROR(os_err_type syserr)
- * @tip Warning: macro implementation; the syserr argument may be evaluated
+ * @warning  macro implementation; the syserr argument may be evaluated
  *      multiple times.
  */
 
 /**
+ * @def APR_TO_OS_ERROR(apr_status_t statcode)
+ * @return os_err_type
  * Fold an apr_status_t code back to the native platform defined error.
  * @param syserr The apr_status_t folded platform os error code.
- * @deffunc os_err_type APR_TO_OS_ERROR(apr_status_t statcode)
- * @tip Warning: macro implementation; the statcode argument may be 
evaluated
+ * @warning  macro implementation; the statcode argument may be evaluated
  *      multiple times.  If the statcode was not created by 
apr_get_os_error
  *      or APR_FROM_OS_ERROR, the results are undefined.
  */
 
 /**
- * Return the last platform error, folded into apr_status_t, on some 
platforms
- * @deffunc apr_status_t apr_get_os_error()
- * @tip This retrieves errno, or calls a GetLastError() style function, and
+ * @def apr_get_os_error()
+ * @return apr_status_t the last platform error, folded into 
apr_status_t, on some platforms
+ * @remark This retrieves errno, or calls a GetLastError() style 
function, and
  *      folds it with APR_FROM_OS_ERROR.  Some platforms (such as OS2) 
have no
  *      such mechanism, so this call may be unsupported.  Some platforms
  *      require the alternate apr_get_netos_error() to retrieve the last
@@ -768,6 +774,7 @@
 
 #endif /* !def OS2 || WIN32 */
 
+/** @} */
 
 #ifdef __cplusplus
 }
Index: apr_file_info.h
===================================================================
RCS file: /home/cvspublic/apr/include/apr_file_info.h,v
retrieving revision 1.20
diff -u -r1.20 apr_file_info.h
--- apr_file_info.h    2001/07/03 12:02:56    1.20
+++ apr_file_info.h    2001/08/11 04:59:41
@@ -68,37 +68,49 @@
 #ifdef __cplusplus
 extern "C" {
 #endif /* __cplusplus */
-
 /**
+ * @file apr_file_info.h
+ * @brief APR File handling
+ */
+/**
+ * @defgroup APR_File_Handle File Handling Functions
+ * @ingroup APR
+ * @{
+ */
+/*
  * @package APR File handling
  */
 
 typedef enum {
-    APR_NOFILE = 0,     /* the file exists, but APR doesn't know its 
type */
-    APR_REG,            /* a regular file */
-    APR_DIR,            /* a directory */
-    APR_CHR,            /* a character device */
-    APR_BLK,            /* a block device */
-    APR_PIPE,           /* a FIFO / pipe */
-    APR_LNK,            /* a symbolic link */
-    APR_SOCK            /* a [unix domain] socket */
+    APR_NOFILE = 0,     /**< the file exists, but APR doesn't know its 
type */
+    APR_REG,            /**< a regular file */
+    APR_DIR,            /**< a directory */
+    APR_CHR,            /**< a character device */
+    APR_BLK,            /**< a block device */
+    APR_PIPE,           /**< a FIFO / pipe */
+    APR_LNK,            /**< a symbolic link */
+    APR_SOCK            /**< a [unix domain] socket */
 } apr_filetype_e;
 
-/* Permissions flags */
+/**
+ * @defgroup APR_file_handle_permission File Permissions flags
+ * @{
+ */
 
-#define APR_UREAD     0x400
-#define APR_UWRITE    0x200
-#define APR_UEXECUTE  0x100
+#define APR_UREAD     0x400 /**< Read by user */
+#define APR_UWRITE    0x200 /**< Write by user */
+#define APR_UEXECUTE  0x100 /**< Execute by user */
 
-#define APR_GREAD     0x040
-#define APR_GWRITE    0x020
-#define APR_GEXECUTE  0x010
+#define APR_GREAD     0x040 /**< Read by group */
+#define APR_GWRITE    0x020 /**< Write by group */
+#define APR_GEXECUTE  0x010 /**< Execute by group */
 
-#define APR_WREAD     0x004
-#define APR_WWRITE    0x002
-#define APR_WEXECUTE  0x001
+#define APR_WREAD     0x004 /**< Read by others */
+#define APR_WWRITE    0x002 /**< Write by others */
+#define APR_WEXECUTE  0x001 /**< Execute by others */
 
-#define APR_OS_DEFAULT 0xFFF
+#define APR_OS_DEFAULT 0xFFF /**< use default permissions of Underlying 
Operating System*/
+/** @} */
 
 /**
  * Structure for referencing directories.
@@ -126,9 +138,13 @@
 typedef dev_t                     apr_dev_t;
 #endif
 
+/**
+ * @defgroup APR_File_Info Stat Functions
+ * @{
+ */
 typedef struct apr_finfo_t        apr_finfo_t;
 
-#define APR_FINFO_LINK   0x00000001
+#define APR_FINFO_LINK   0x00000001 /**< Stat the link not the file 
itself if it is a link */
 #define APR_FINFO_MTIME  0x00000010
 #define APR_FINFO_CTIME  0x00000020
 #define APR_FINFO_ATIME  0x00000040
@@ -143,15 +159,15 @@
 #define APR_FINFO_UPROT  0x00100000
 #define APR_FINFO_GPROT  0x00200000
 #define APR_FINFO_WPROT  0x00400000
-#define APR_FINFO_ICASE  0x01000000  /*  if dev is case insensitive */
-#define APR_FINFO_NAME   0x02000000  /*  ->name in proper case */
+#define APR_FINFO_ICASE  0x01000000  /**<  if dev is case insensitive */
+#define APR_FINFO_NAME   0x02000000  /**<  ->name in proper case */
 
-#define APR_FINFO_MIN    0x00008170  /*  type, mtime, ctime, atime, size */
-#define APR_FINFO_IDENT  0x00003000  /*  dev and inode */
-#define APR_FINFO_OWNER  0x00030000  /*  user and group */
-#define APR_FINFO_PROT   0x00700000  /*  all protections */
-#define APR_FINFO_NORM   0x0073b170  /*  an atomic unix apr_stat() */
-#define APR_FINFO_DIRENT 0x02000000  /*  an atomic unix apr_dir_read() */
+#define APR_FINFO_MIN    0x00008170  /**<  type, mtime, ctime, atime, 
size */
+#define APR_FINFO_IDENT  0x00003000  /**<  dev and inode */
+#define APR_FINFO_OWNER  0x00030000  /**<  user and group */
+#define APR_FINFO_PROT   0x00700000  /**<  all protections */
+#define APR_FINFO_NORM   0x0073b170  /**<  an atomic unix apr_stat() */
+#define APR_FINFO_DIRENT 0x02000000  /**<  an atomic unix apr_dir_read() */
 
 /**
  * The file information structure.  This is analogous to the POSIX
@@ -205,7 +221,6 @@
  * @param fname The name of the file to stat.
  * @param wanted The desired apr_finfo_t fields, as a bit flag of 
APR_FINFO_ values
  * @param cont the pool to use to allocate the new file.
- * @deffunc apr_status_t apr_stat(apr_finfo_t *finfo, const char 
*fname, apr_int32_t wanted, apr_pool_t *cont)
  */
 APR_DECLARE(apr_status_t) apr_stat(apr_finfo_t *finfo, const char *fname,
                                    apr_int32_t wanted, apr_pool_t *cont);
@@ -219,19 +234,22 @@
  * @param fname The name of the file to stat.
  * @param wanted The desired apr_finfo_t fields, as a bit flag of 
APR_FINFO_ values
  * @param cont the pool to use to allocate the new file.
- * @deffunc apr_status_t apr_lstat(apr_finfo_t *finfo, const char 
*fname, apr_int32_t wanted, apr_pool_t *cont)
- * @tip This function is depreciated, it's equivilant to calling 
apr_stat with
+ * @deprecated This function is depreciated, it's equivilant to calling 
apr_stat with
  * the wanted flag value APR_FINFO_LINK
  */
 APR_DECLARE(apr_status_t) apr_lstat(apr_finfo_t *finfo, const char *fname,
                                     apr_int32_t wanted, apr_pool_t *cont);
+/** @} */
+/**
+ * @defgroup APR_DIRECTORY Directory Manipulation Functions
+ * @{
+ */
 
 /**
  * Open the specified directory.
  * @param new_dir The opened directory descriptor.
  * @param dirname The full path to the directory (use / on all systems)
  * @param cont The pool to use.
- * @deffunc apr_status_t apr_dir_open(apr_dir_t **new_dir, const char 
*dirname, apr_pool_t *cont)
  */                        
 APR_DECLARE(apr_status_t) apr_dir_open(apr_dir_t **new_dir,
                                        const char *dirname,
@@ -240,7 +258,6 @@
 /**
  * close the specified directory.
  * @param thedir the directory descriptor to close.
- * @deffunc apr_status_t apr_dir_close(apr_dir_t *thedir)
  */                        
 APR_DECLARE(apr_status_t) apr_dir_close(apr_dir_t *thedir);
 
@@ -249,8 +266,7 @@
  * @param finfo the file info structure and filled in by apr_dir_read
  * @param wanted The desired apr_finfo_t fields, as a bit flag of 
APR_FINFO_ values
  * @param thedir the directory descriptor returned from apr_dir_open
- * @tip All systems return . and .. as the first two files.
- * @deffunc apr_status_t apr_dir_read(apr_finfo_t *finfo, apr_int32_t 
wanted, apr_dir_t *thedir)
+ * @remark All systems return . and .. as the first two files.
  */                        
 APR_DECLARE(apr_status_t) apr_dir_read(apr_finfo_t *finfo, apr_int32_t 
wanted,
                                        apr_dir_t *thedir);
@@ -258,42 +274,45 @@
 /**
  * Rewind the directory to the first entry.
  * @param thedir the directory descriptor to rewind.
- * @deffunc apr_status_t apr_dir_rewind(apr_dir_t *thedir)
  */                        
 APR_DECLARE(apr_status_t) apr_dir_rewind(apr_dir_t *thedir);
+/** @} */
 
-/* apr_filepath optional flags
+/**
+ * @defgroup apr_filepath FilePath Manipulation operations
+ * @{
  */
 
-/* Cause apr_filepath_merge to fail if addpath is above rootpath */
+/** Cause apr_filepath_merge to fail if addpath is above rootpath */
 #define APR_FILEPATH_NOTABOVEROOT   0x01
 
-/* internal: Only meaningful with APR_FILEPATH_NOTABOVEROOT */
+/** internal: Only meaningful with APR_FILEPATH_NOTABOVEROOT */
 #define APR_FILEPATH_SECUREROOTTEST 0x02
 
-/* Cause apr_filepath_merge to fail if addpath is above rootpath,
+/** Cause apr_filepath_merge to fail if addpath is above rootpath,
  * even given a rootpath /foo/bar and an addpath ../bar/bash
  */
 #define APR_FILEPATH_SECUREROOT     0x03
 
-/* Fail apr_filepath_merge if the merged path is relative */
+/** Fail apr_filepath_merge if the merged path is relative */
 #define APR_FILEPATH_NOTRELATIVE    0x04
 
-/* Fail apr_filepath_merge if the merged path is absolute */
+/** Fail apr_filepath_merge if the merged path is absolute */
 #define APR_FILEPATH_NOTABSOLUTE    0x08
 
-/* Return the file system's native path format (e.g. path delimiters
+/** Return the file system's native path format (e.g. path delimiters
  * of ':' on MacOS9, '\' on Win32, etc.) */
 #define APR_FILEPATH_NATIVE         0x10
 
-/* Resolve the true case of existing directories and file elements
+/** Resolve the true case of existing directories and file elements
  * of addpath, (resolving any aliases on Win32) and append a proper
  * trailing slash if a directory
  */
 #define APR_FILEPATH_TRUENAME       0x20
-
+/** @} */
 /**
  * Extract the rootpath from the given filepath
+ * @ingroup apr_filepath
  * @param rootpath the root file path returned with APR_SUCCESS or 
APR_EINCOMPLETE
  * @param filepath the pathname to parse for it's root component
  * @param flags the desired rules to apply, from
@@ -303,7 +322,7 @@
  * </PRE>
  * @param p the pool to allocate the new path string from
  * @deffunc apr_status_t apr_filepath_root(const char **rootpath, const 
char **inpath, apr_int32_t flags, apr_pool_t *p)
- * @tip on return, filepath points to the first non-root character in the
+ * @remark on return, filepath points to the first non-root character 
in the
  * given filepath.  In the simplest example, given a filepath of "/foo",
  * returns the rootpath of "/" and filepath points at "foo".  This is far
  * more complex on other platforms, which will canonicalize the root form
@@ -323,6 +342,7 @@
 
 /**
  * Merge additional file path onto the previously processed rootpath
+ * @ingroup apr_filepath
  * @param newpath the merged paths returned
  * @param rootpath the root file path (NULL uses the current working path)
  * @param addpath the path to add to the root path
@@ -338,6 +358,7 @@
 
 /**
  * Return the default file path (for relative file names)
+ * @ingroup apr_filepath
  * @param path the default path string returned
  * @param p the pool to allocate the default path string from
  * @deffunc apr_status_t apr_filepath_get(char **path, apr_pool_t *p)
@@ -346,12 +367,14 @@
 
 /**
  * Set the default file path (for relative file names)
+ * @ingroup apr_filepath
  * @param path the default path returned
  * @param p the pool to allocate any working storage
  * @deffunc apr_status_t apr_filepath_get(char **defpath, apr_pool_t *p)
  */
 APR_DECLARE(apr_status_t) apr_filepath_set(const char *path, apr_pool_t 
*p);
 
+/** @} */
 
 #ifdef __cplusplus
 }
Index: apr_pools.h
===================================================================
RCS file: /home/cvspublic/apr/include/apr_pools.h,v
retrieving revision 1.55
diff -u -r1.55 apr_pools.h
--- apr_pools.h    2001/08/02 05:24:42    1.55
+++ apr_pools.h    2001/08/11 04:59:42
@@ -79,7 +79,11 @@
  * we can delete everything in the per-transaction apr_pool_t without 
fear,
  * and without thinking too hard about it either.
  */
-
+/**
+ * @defgroup APR_Pool Pool Allocation Functions
+ * @ingroup APR
+ * @{
+ */
 #include "apr.h"
 #include "apr_errno.h"
 
@@ -489,7 +493,7 @@
 #define apr_pool_destroy apr_sms_destroy
 
 #endif /* APR_POOLS_ARE_SMS */
-
+/** @} */
 #ifdef __cplusplus
 }
 #endif


Mime
View raw message