apr-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ryan Bloom <...@covalent.net>
Subject Re: [PATCH] Doxygen'ization of apr_file_info/apr_pool/apr_errno/apr
Date Sat, 11 Aug 2001 16:29:48 GMT


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
--------------------------------------------------------------

Mime
View raw message