You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@apr.apache.org by Ryan Bloom <rb...@covalent.net> on 2001/08/11 18:29:48 UTC
Re: [PATCH] Doxygen'ization of apr_file_info/apr_pool/apr_errno/apr
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 rbb@apache.org
Covalent Technologies rbb@covalent.net
--------------------------------------------------------------