* include/apr_file_io.h: Doxygen/formatting/whitespace cleanups.

git-svn-id: http://svn.apache.org/repos/asf/apr/apr/trunk@65137 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 107 insertions, 113 deletions

diff --git a/include/apr_file_io.h b/include/apr_file_io.h
index c1d32bcdf..5e7f0d282 100644
--- a/include/apr_file_io.h
+++ b/include/apr_file_io.h
@@ -113,7 +113,7 @@ extern "C" {
 /** File attributes */
 typedef apr_uint32_t apr_fileattrs_t;
 
-/** should be same as whence type in lseek, POSIX defines this as int */
+/** Type to pass as whence argument to apr_file_seek. */
 typedef int       apr_seek_where_t;
 
 /**
@@ -145,7 +145,7 @@ typedef struct apr_file_t         apr_file_t;
 
 /**
  * Open the specified file.
- * @param new_file The opened file descriptor.
+ * @param newf The opened file descriptor.
  * @param fname The full path to the file (using / on all systems)
  * @param flag Or'ed value of:
  * <PRE>
@@ -174,8 +174,8 @@ typedef struct apr_file_t         apr_file_t;
  * </PRE>
  * @param perm Access permissions for file.
  * @param pool The pool to use.
- * @remark If perm is APR_OS_DEFAULT and the file is being created, appropriate 
- *      default permissions will be used.
+ * @remark If perm is APR_OS_DEFAULT and the file is being created,
+ * appropriate default permissions will be used.
  */
 APR_DECLARE(apr_status_t) apr_file_open(apr_file_t **newf, const char *fname,
                                         apr_int32_t flag, apr_fileperms_t perm,
@@ -188,27 +188,29 @@ APR_DECLARE(apr_status_t) apr_file_open(apr_file_t **newf, const char *fname,
 APR_DECLARE(apr_status_t) apr_file_close(apr_file_t *file);
 
 /**
- * delete the specified file.
+ * Delete the specified file.
  * @param path The full path to the file (using / on all systems)
  * @param pool The pool to use.
- * @remark If the file is open, it won't be removed until all instances are closed.
+ * @remark If the file is open, it won't be removed until all
+ * instances are closed.
  */
 APR_DECLARE(apr_status_t) apr_file_remove(const char *path, apr_pool_t *pool);
 
 /**
- * rename the specified file.
+ * Rename the specified file.
  * @param from_path The full path to the original file (using / on all systems)
  * @param to_path The full path to the new file (using / on all systems)
  * @param pool The pool to use.
- * @warning If a file exists at the new location, then it will be overwritten.  
- *      Moving files or directories across devices may not be possible.
+ * @warning If a file exists at the new location, then it will be
+ * overwritten.  Moving files or directories across devices may not be
+ * possible.
  */
 APR_DECLARE(apr_status_t) apr_file_rename(const char *from_path, 
                                           const char *to_path,
                                           apr_pool_t *pool);
 
 /**
- * copy the specified file to another file.
+ * Copy the specified file to another file.
  * @param from_path The full path to the original file (using / on all systems)
  * @param to_path The full path to the new file (using / on all systems)
  * @param perms Access permissions for the new file if it is created.
@@ -225,9 +227,9 @@ APR_DECLARE(apr_status_t) apr_file_copy(const char *from_path,
                                         apr_pool_t *pool);
 
 /**
- * append the specified file to another file.
- * @param from_path The full path to the source file (using / on all systems)
- * @param to_path The full path to the destination file (using / on all systems)
+ * Append the specified file to another file.
+ * @param from_path The full path to the source file (use / on all systems)
+ * @param to_path The full path to the destination file (use / on all systems)
  * @param perms Access permissions for the destination file if it is created.
  *     In place of the usual or'd combination of file permissions, the
  *     value APR_FILE_SOURCE_PERMS may be given, in which case the source
@@ -248,7 +250,7 @@ APR_DECLARE(apr_status_t) apr_file_append(const char *from_path,
 APR_DECLARE(apr_status_t) apr_file_eof(apr_file_t *fptr);
 
 /**
- * open standard error as an apr file pointer.
+ * Open standard error as an apr file pointer.
  * @param thefile The apr file to use as stderr.
  * @param pool The pool to allocate the file out of.
  * 
@@ -256,7 +258,7 @@ APR_DECLARE(apr_status_t) apr_file_eof(apr_file_t *fptr);
  * is that you may not always have a stderr/out/in on Windows.  This
  * is generally a problem with newer versions of Windows and services.
  * 
- * The other problem is that the C library functions generally work
+ * @remark The other problem is that the C library functions generally work
  * differently on Windows and Unix.  So, by using apr_file_open_std*
  * functions, you can get a handle to an APR struct that works with
  * the APR functions which are supposed to work identically on all
@@ -270,15 +272,7 @@ APR_DECLARE(apr_status_t) apr_file_open_stderr(apr_file_t **thefile,
  * @param thefile The apr file to use as stdout.
  * @param pool The pool to allocate the file out of.
  * 
- * @remark The only reason that the apr_file_open_std* functions exist
- * is that you may not always have a stderr/out/in on Windows.  This
- * is generally a problem with newer versions of Windows and services.
- * 
- * The other problem is that the C library functions generally work
- * differently on Windows and Unix.  So, by using apr_file_open_std*
- * functions, you can get a handle to an APR struct that works with
- * the APR functions which are supposed to work identically on all
- * platforms.
+ * @remark See remarks for apr_file_open_stdout.
  */
 APR_DECLARE(apr_status_t) apr_file_open_stdout(apr_file_t **thefile,
                                                apr_pool_t *pool);
@@ -288,15 +282,7 @@ APR_DECLARE(apr_status_t) apr_file_open_stdout(apr_file_t **thefile,
  * @param thefile The apr file to use as stdin.
  * @param pool The pool to allocate the file out of.
  * 
- * @remark The only reason that the apr_file_open_std* functions exist
- * is that you may not always have a stderr/out/in on Windows.  This
- * is generally a problem with newer versions of Windows and services.
- * 
- * The other problem is that the C library functions generally work
- * differently on Windows and Unix.  So, by using apr_file_open_std*
- * functions, you can get a handle to an APR struct that works with
- * the APR functions which are supposed to work identically on all
- * platforms.
+ * @remark See remarks for apr_file_open_stdout.
  */
 APR_DECLARE(apr_status_t) apr_file_open_stdin(apr_file_t **thefile,
                                               apr_pool_t *pool);
@@ -305,21 +291,21 @@ APR_DECLARE(apr_status_t) apr_file_open_stdin(apr_file_t **thefile,
  * Read data from the specified file.
  * @param thefile The file descriptor to read from.
  * @param buf The buffer to store the data to.
- * @param nbytes On entry, the number of bytes to read; on exit, the number of bytes read.
- * @remark apr_file_read will read up to the specified number of bytes, but 
- *         never more.  If there isn't enough data to fill that number of 
- *         bytes, all of the available data is read.  The third argument is 
- *         modified to reflect the number of bytes read.  If a char was put 
- *         back into the stream via ungetc, it will be the first character 
- *         returned. 
+ * @param nbytes On entry, the number of bytes to read; on exit, the number
+ * of bytes read.
  *
- *         It is not possible for both bytes to be read and an APR_EOF or other 
- *         error to be returned.
+ * @remark apr_file_read will read up to the specified number of
+ * bytes, but never more.  If there isn't enough data to fill that
+ * number of bytes, all of the available data is read.  The third
+ * argument is modified to reflect the number of bytes read.  If a
+ * char was put back into the stream via ungetc, it will be the first
+ * character returned.
  *
- *         APR_EINTR is never returned.
+ * @remark It is not possible for both bytes to be read and an APR_EOF
+ * or other error to be returned.  APR_EINTR is never returned.
  */
 APR_DECLARE(apr_status_t) apr_file_read(apr_file_t *thefile, void *buf,
-                                   apr_size_t *nbytes);
+                                        apr_size_t *nbytes);
 
 /**
  * Write data to the specified file.
@@ -327,17 +313,17 @@ APR_DECLARE(apr_status_t) apr_file_read(apr_file_t *thefile, void *buf,
  * @param buf The buffer which contains the data.
  * @param nbytes On entry, the number of bytes to write; on exit, the number 
  *               of bytes written.
- * @remark apr_file_write will write up to the specified number of bytes, but never 
- *      more.  If the OS cannot write that many bytes, it will write as many 
- *      as it can.  The third argument is modified to reflect the * number 
- *      of bytes written. 
  *
- *      It is possible for both bytes to be written and an error to be returned.
+ * @remark apr_file_write will write up to the specified number of
+ * bytes, but never more.  If the OS cannot write that many bytes, it
+ * will write as many as it can.  The third argument is modified to
+ * reflect the * number of bytes written.
  *
- *      APR_EINTR is never returned.
+ * @remark It is possible for both bytes to be written and an error to
+ * be returned.  APR_EINTR is never returned.
  */
 APR_DECLARE(apr_status_t) apr_file_write(apr_file_t *thefile, const void *buf,
-                                    apr_size_t *nbytes);
+                                         apr_size_t *nbytes);
 
 /**
  * Write data from iovec array to the specified file.
@@ -347,16 +333,16 @@ APR_DECLARE(apr_status_t) apr_file_write(apr_file_t *thefile, const void *buf,
  *             be smaller than APR_MAX_IOVEC_SIZE.  If it isn't, the function 
  *             will fail with APR_EINVAL.
  * @param nbytes The number of bytes written.
- * @remark It is possible for both bytes to be written and an error to be returned.
- *      APR_EINTR is never returned.
  *
- *      apr_file_writev is available even if the underlying operating system 
+ * @remark It is possible for both bytes to be written and an error to
+ * be returned.  APR_EINTR is never returned.
  *
- *      doesn't provide writev().
+ * @remark apr_file_writev is available even if the underlying
+ * operating system doesn't provide writev().
  */
 APR_DECLARE(apr_status_t) apr_file_writev(apr_file_t *thefile,
-                                     const struct iovec *vec,
-                                     apr_size_t nvec, apr_size_t *nbytes);
+                                          const struct iovec *vec,
+                                          apr_size_t nvec, apr_size_t *nbytes);
 
 /**
  * Read data from the specified file, ensuring that the buffer is filled
@@ -365,21 +351,22 @@ APR_DECLARE(apr_status_t) apr_file_writev(apr_file_t *thefile,
  * @param buf The buffer to store the data to.
  * @param nbytes The number of bytes to read.
  * @param bytes_read If non-NULL, this will contain the number of bytes read.
- * @remark apr_file_read will read up to the specified number of bytes, but never 
- *      more.  If there isn't enough data to fill that number of bytes, 
- *      then the process/thread will block until it is available or EOF 
- *      is reached.  If a char was put back into the stream via ungetc, 
- *      it will be the first character returned. 
  *
- *      It is possible for both bytes to be read and an error to be 
- *      returned.  And if *bytes_read is less than nbytes, an
- *      accompanying error is _always_ returned.
+ * @remark apr_file_read will read up to the specified number of
+ * bytes, but never more.  If there isn't enough data to fill that
+ * number of bytes, then the process/thread will block until it is
+ * available or EOF is reached.  If a char was put back into the
+ * stream via ungetc, it will be the first character returned.
+ *
+ * @remark It is possible for both bytes to be read and an error to be
+ * returned.  And if *bytes_read is less than nbytes, an accompanying
+ * error is _always_ returned.
  *
- *      APR_EINTR is never returned.
+ * @remark APR_EINTR is never returned.
  */
 APR_DECLARE(apr_status_t) apr_file_read_full(apr_file_t *thefile, void *buf,
-                                        apr_size_t nbytes,
-                                        apr_size_t *bytes_read);
+                                             apr_size_t nbytes,
+                                             apr_size_t *bytes_read);
 
 /**
  * Write data to the specified file, ensuring that all of the data is
@@ -387,54 +374,58 @@ APR_DECLARE(apr_status_t) apr_file_read_full(apr_file_t *thefile, void *buf,
  * @param thefile The file descriptor to write to.
  * @param buf The buffer which contains the data.
  * @param nbytes The number of bytes to write.
- * @param bytes_written If non-NULL, this will contain the number of bytes written.
- * @remark apr_file_write will write up to the specified number of bytes, but never 
- *      more.  If the OS cannot write that many bytes, the process/thread 
- *      will block until they can be written. Exceptional error such as 
- *      "out of space" or "pipe closed" will terminate with an error.
+ * @param bytes_written If non-NULL, set to the number of bytes written.
+ * 
+ * @remark apr_file_write will write up to the specified number of
+ * bytes, but never more.  If the OS cannot write that many bytes, the
+ * process/thread will block until they can be written. Exceptional
+ * error such as "out of space" or "pipe closed" will terminate with
+ * an error.
  *
- *      It is possible for both bytes to be written and an error to be 
- *      returned.  And if *bytes_written is less than nbytes, an
- *      accompanying error is _always_ returned.
+ * @remark It is possible for both bytes to be written and an error to
+ * be returned.  And if *bytes_written is less than nbytes, an
+ * accompanying error is _always_ returned.
  *
- *      APR_EINTR is never returned.
+ * @remark APR_EINTR is never returned.
  */
-APR_DECLARE(apr_status_t) apr_file_write_full(apr_file_t *thefile, const void *buf,
-                                         apr_size_t nbytes, 
-                                         apr_size_t *bytes_written);
+APR_DECLARE(apr_status_t) apr_file_write_full(apr_file_t *thefile, 
+                                              const void *buf,
+                                              apr_size_t nbytes, 
+                                              apr_size_t *bytes_written);
 
 /**
- * put a character into the specified file.
+ * Write a character into the specified file.
  * @param ch The character to write.
  * @param thefile The file descriptor to write to
  */
 APR_DECLARE(apr_status_t) apr_file_putc(char ch, apr_file_t *thefile);
 
 /**
- * get a character from the specified file.
+ * Read a character from the specified file.
  * @param ch The character to read into
  * @param thefile The file descriptor to read from
  */
 APR_DECLARE(apr_status_t) apr_file_getc(char *ch, apr_file_t *thefile);
 
 /**
- * put a character back onto a specified stream.
+ * Put a character back onto a specified stream.
  * @param ch The character to write.
  * @param thefile The file descriptor to write to
  */
 APR_DECLARE(apr_status_t) apr_file_ungetc(char ch, apr_file_t *thefile);
 
 /**
- * Get a string from a specified file.
+ * Read a string from the specified file.
  * @param str The buffer to store the string in. 
  * @param len The length of the string
  * @param thefile The file descriptor to read from
  * @remark The buffer will be NUL-terminated if any characters are stored.
  */
-APR_DECLARE(apr_status_t) apr_file_gets(char *str, int len, apr_file_t *thefile);
+APR_DECLARE(apr_status_t) apr_file_gets(char *str, int len, 
+                                        apr_file_t *thefile);
 
 /**
- * Put the string into a specified file.
+ * Write the string into the specified file.
  * @param str The string to write. 
  * @param thefile The file descriptor to write to
  */
@@ -447,30 +438,30 @@ APR_DECLARE(apr_status_t) apr_file_puts(const char *str, apr_file_t *thefile);
 APR_DECLARE(apr_status_t) apr_file_flush(apr_file_t *thefile);
 
 /**
- * duplicate the specified file descriptor.
+ * Duplicate the specified file descriptor.
  * @param new_file The structure to duplicate into. 
  * @param old_file The file to duplicate.
  * @param p The pool to use for the new file.
- * @remark *new_file must point to a valid apr_file_t, or point to NULL
+ * @remark *new_file must point to a valid apr_file_t, or point to NULL.
  */         
 APR_DECLARE(apr_status_t) apr_file_dup(apr_file_t **new_file,
-                                      apr_file_t *old_file,
-                                      apr_pool_t *p);
+                                       apr_file_t *old_file,
+                                       apr_pool_t *p);
 
 /**
- * duplicate the specified file descriptor and close the original
+ * Duplicate the specified file descriptor and close the original
  * @param new_file The old file that is to be closed and reused
  * @param old_file The file to duplicate
  * @param p        The pool to use for the new file
  *
- * @remark new_file MUST point at a valid apr_file_t. It cannot be NULL
+ * @remark new_file MUST point at a valid apr_file_t. It cannot be NULL.
  */
 APR_DECLARE(apr_status_t) apr_file_dup2(apr_file_t *new_file,
                                         apr_file_t *old_file,
                                         apr_pool_t *p);
 
 /**
- * move the specified file descriptor to a new pool
+ * Move the specified file descriptor to a new pool
  * @param new_file Pointer in which to return the new apr_file_t
  * @param old_file The file to move
  * @param p        The pool to which the descriptor is to be moved
@@ -507,7 +498,8 @@ APR_DECLARE(apr_status_t) apr_file_seek(apr_file_t *thefile,
  * @param out The file descriptor to use as output from the pipe.
  * @param pool The pool to operate on.
  */
-APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in, apr_file_t **out,
+APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in, 
+                                               apr_file_t **out,
                                                apr_pool_t *pool);
 
 /**
@@ -517,8 +509,8 @@ APR_DECLARE(apr_status_t) apr_file_pipe_create(apr_file_t **in, apr_file_t **out
  * @param pool The pool to operate on.
  */
 APR_DECLARE(apr_status_t) apr_file_namedpipe_create(const char *filename, 
-                                               apr_fileperms_t perm, 
-                                               apr_pool_t *pool);
+                                                    apr_fileperms_t perm, 
+                                                    apr_pool_t *pool);
 
 /**
  * Get the timeout value for a pipe or manipulate the blocking state.
@@ -535,7 +527,7 @@ APR_DECLARE(apr_status_t) apr_file_pipe_timeout_get(apr_file_t *thepipe,
  *        forever, 0 means do not wait at all.
  */
 APR_DECLARE(apr_status_t) apr_file_pipe_timeout_set(apr_file_t *thepipe, 
-                                               apr_interval_time_t timeout);
+                                                  apr_interval_time_t timeout);
 
 /** file (un)locking functions. */
 
@@ -564,8 +556,8 @@ APR_DECLARE(apr_status_t) apr_file_unlock(apr_file_t *thefile);
  * @param thefile The currently open file.
  */                     
 APR_DECLARE(apr_status_t) apr_file_name_get(const char **new_path, 
-                                           apr_file_t *thefile);
-
+                                            apr_file_t *thefile);
+    
 /**
  * Return the data associated with the current file.
  * @param data The user data associated with the file.  
@@ -573,7 +565,7 @@ APR_DECLARE(apr_status_t) apr_file_name_get(const char **new_path,
  * @param file The currently open file.
  */                     
 APR_DECLARE(apr_status_t) apr_file_data_get(void **data, const char *key, 
-                                           apr_file_t *file);
+                                            apr_file_t *file);
 
 /**
  * Set the data associated with the current file.
@@ -583,8 +575,8 @@ APR_DECLARE(apr_status_t) apr_file_data_get(void **data, const char *key,
  * @param cleanup The cleanup routine to use when the file is destroyed.
  */                     
 APR_DECLARE(apr_status_t) apr_file_data_set(apr_file_t *file, void *data,
-                                           const char *key,
-                                           apr_status_t (*cleanup)(void *));
+                                            const char *key,
+                                            apr_status_t (*cleanup)(void *));
 
 /**
  * Write a string to a file using a printf format.
@@ -601,14 +593,16 @@ APR_DECLARE_NONSTD(int) apr_file_printf(apr_file_t *fptr,
  * set the specified file's permission bits.
  * @param fname The file (name) to apply the permissions to.
  * @param perms The permission bits to apply to the file.
- * @warning Some platforms may not be able to apply all of the available 
- *      permission bits; APR_INCOMPLETE will be returned if some permissions 
- *      are specified which could not be set.
  *
- *      Platforms which do not implement this feature will return APR_ENOTIMPL.
+ * @warning Some platforms may not be able to apply all of the
+ * available permission bits; APR_INCOMPLETE will be returned if some
+ * permissions are specified which could not be set.
+ *
+ * @warning Platforms which do not implement this feature will return
+ * APR_ENOTIMPL.
  */
 APR_DECLARE(apr_status_t) apr_file_perms_set(const char *fname,
-                                           apr_fileperms_t perms);
+                                             apr_fileperms_t perms);
 
 /**
  * Set attributes of the specified file.
@@ -647,7 +641,7 @@ APR_DECLARE(apr_status_t) apr_file_mtime_set(const char *fname,
 
 /**
  * Create a new directory on the file system.
- * @param path the path for the directory to be created.  (use / on all systems)
+ * @param path the path for the directory to be created. (use / on all systems)
  * @param perm Permissions for the new direcoty.
  * @param pool the pool to use.
  */                        
@@ -657,7 +651,7 @@ APR_DECLARE(apr_status_t) apr_dir_make(const char *path, apr_fileperms_t perm,
 /** Creates a new directory on the file system, but behaves like
  * 'mkdir -p'. Creates intermediate directories as required. No error
  * will be reported if PATH already exists.
- * @param path the path for the directory to be created.  (use / on all systems)
+ * @param path the path for the directory to be created. (use / on all systems)
  * @param perm Permissions for the new direcoty.
  * @param pool the pool to use.
  */
@@ -667,7 +661,7 @@ APR_DECLARE(apr_status_t) apr_dir_make_recursive(const char *path,
 
 /**
  * Remove directory from the file system.
- * @param path the path for the directory to be removed.  (use / on all systems)
+ * @param path the path for the directory to be removed. (use / on all systems)
  * @param pool the pool to use.
  */                        
 APR_DECLARE(apr_status_t) apr_dir_remove(const char *path, apr_pool_t *pool);
@@ -679,9 +673,9 @@ APR_DECLARE(apr_status_t) apr_dir_remove(const char *path, apr_pool_t *pool);
  * @param thefile The file to get information about.
  */ 
 APR_DECLARE(apr_status_t) apr_file_info_get(apr_finfo_t *finfo, 
-                                          apr_int32_t wanted,
-                                          apr_file_t *thefile);
-
+                                            apr_int32_t wanted,
+                                            apr_file_t *thefile);
+    
 
 /**
  * Truncate the file's length to the specified offset