I'll be committing this later today unless somebody beats me to it.
Keep these coming. Ryan On Friday 10 August 2001 22:12, Ian Holsman wrote: > 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 ---------------------------------------- Content-Type: text/plain; charset="us-ascii"; name="apr_dox.patch" Content-Transfer-Encoding: 7bit Content-Description: ---------------------------------------- -- ______________________________________________________________ Ryan Bloom [EMAIL PROTECTED] Covalent Technologies [EMAIL PROTECTED] --------------------------------------------------------------
