Merge r1559382,1571894,1587545 from trunk:
Doxygen and general doc fixes
git-svn-id: https://svn.apache.org/repos/asf/apr/apr/branches/1.5.x@1587585 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/include/apr_file_info.h b/include/apr_file_info.h
index b3006ac..1d19eb6 100644
--- a/include/apr_file_info.h
+++ b/include/apr_file_info.h
@@ -208,7 +208,7 @@
const char *fname;
/** The file's name (no path) in filesystem case */
const char *name;
- /** The file's handle, if accessed (can be submitted to apr_duphandle) */
+ /** Unused */
struct apr_file_t *filehand;
};
diff --git a/include/apr_fnmatch.h b/include/apr_fnmatch.h
index ef6d0b2..e8f6b03 100644
--- a/include/apr_fnmatch.h
+++ b/include/apr_fnmatch.h
@@ -60,9 +60,7 @@
#define APR_FNM_NOESCAPE 0x01 /**< Disable backslash escaping. */
#define APR_FNM_PATHNAME 0x02 /**< Slash must be matched by slash. */
#define APR_FNM_PERIOD 0x04 /**< Period must be matched by period. */
-#define APR_FNM_CASE_BLIND 0x08 /**< Compare characters case-insensitively.
- * @remark This flag is an Apache addition
- */
+#define APR_FNM_CASE_BLIND 0x08 /**< Compare characters case-insensitively. */
/**
* Try to match the string to the given pattern, return APR_SUCCESS if
@@ -130,13 +128,19 @@
APR_DECLARE(int) apr_fnmatch_test(const char *pattern);
/**
- * Find all files that match a specified pattern.
- * @param pattern The pattern to use for finding files.
+ * Find all files that match a specified pattern in a directory.
+ * @param dir_pattern The pattern to use for finding files, appended
+ * to the search directory. The pattern is anything following the
+ * final forward or backward slash in the parameter. If no slash
+ * is found, the current directory is searched.
* @param result Array to use when storing the results
* @param p The pool to use.
- * @return non-zero if pattern has any glob characters in it
+ * @return APR_SUCCESS if no processing errors occurred, APR error
+ * code otherwise
+ * @remark The returned array may be empty even if APR_SUCCESS was
+ * returned.
*/
-APR_DECLARE(apr_status_t) apr_match_glob(const char *pattern,
+APR_DECLARE(apr_status_t) apr_match_glob(const char *dir_pattern,
apr_array_header_t **result,
apr_pool_t *p);
diff --git a/include/apr_poll.h b/include/apr_poll.h
index fd0e589..1381ddd 100644
--- a/include/apr_poll.h
+++ b/include/apr_poll.h
@@ -42,7 +42,9 @@
*/
/**
- * Poll options
+ * @defgroup pollopts Poll options
+ * @ingroup apr_poll
+ * @{
*/
#define APR_POLLIN 0x001 /**< Can read without blocking */
#define APR_POLLPRI 0x002 /**< Priority data available */
@@ -50,9 +52,12 @@
#define APR_POLLERR 0x010 /**< Pending error */
#define APR_POLLHUP 0x020 /**< Hangup occurred */
#define APR_POLLNVAL 0x040 /**< Descriptor invalid */
+/** @} */
/**
- * Pollset Flags
+ * @defgroup pollflags Pollset Flags
+ * @ingroup apr_poll
+ * @{
*/
#define APR_POLLSET_THREADSAFE 0x001 /**< Adding or removing a descriptor is
* thread-safe
@@ -67,6 +72,7 @@
* the specified non-default method cannot be
* used
*/
+/** @} */
/**
* Pollset Methods
diff --git a/include/apr_thread_mutex.h b/include/apr_thread_mutex.h
index 4596dce..193a70a 100644
--- a/include/apr_thread_mutex.h
+++ b/include/apr_thread_mutex.h
@@ -59,7 +59,7 @@
* </PRE>
* @param pool the pool from which to allocate the mutex.
* @warning Be cautious in using APR_THREAD_MUTEX_DEFAULT. While this is the
- * most optimial mutex based on a given platform's performance charateristics,
+ * most optimal mutex based on a given platform's performance characteristics,
* it will behave as either a nested or an unnested lock.
*/
APR_DECLARE(apr_status_t) apr_thread_mutex_create(apr_thread_mutex_t **mutex,
diff --git a/include/apr_time.h b/include/apr_time.h
index 6dd70cc..15e0b96 100644
--- a/include/apr_time.h
+++ b/include/apr_time.h
@@ -42,7 +42,7 @@
APR_DECLARE_DATA extern const char apr_day_snames[7][4];
-/** number of microseconds since 00:00:00 january 1, 1970 UTC */
+/** number of microseconds since 00:00:00 January 1, 1970 UTC */
typedef apr_int64_t apr_time_t;
@@ -93,7 +93,7 @@
/**
* a structure similar to ANSI struct tm with the following differences:
* - tm_usec isn't an ANSI field
- * - tm_gmtoff isn't an ANSI field (it's a bsdism)
+ * - tm_gmtoff isn't an ANSI field (it's a BSDism)
*/
struct apr_time_exp_t {
/** microseconds past tm_sec */
@@ -110,9 +110,9 @@
apr_int32_t tm_mon;
/** year since 1900 */
apr_int32_t tm_year;
- /** (0-6) days since sunday */
+ /** (0-6) days since Sunday */
apr_int32_t tm_wday;
- /** (0-365) days since jan 1 */
+ /** (0-365) days since January 1 */
apr_int32_t tm_yday;
/** daylight saving time */
apr_int32_t tm_isdst;
@@ -121,7 +121,7 @@
};
/**
- * convert an ansi time_t to an apr_time_t
+ * Convert an ansi time_t to an apr_time_t
* @param result the resulting apr_time_t
* @param input the time_t to convert
*/
@@ -129,8 +129,8 @@
time_t input);
/**
- * convert a time to its human readable components using an offset
- * from GMT
+ * Convert a time to its human readable components using an offset
+ * from GMT.
* @param result the exploded time
* @param input the time to explode
* @param offs the number of seconds offset to apply
@@ -140,7 +140,7 @@
apr_int32_t offs);
/**
- * convert a time to its human readable components in GMT timezone
+ * Convert a time to its human readable components (GMT).
* @param result the exploded time
* @param input the time to explode
*/
@@ -148,7 +148,7 @@
apr_time_t input);
/**
- * convert a time to its human readable components in local timezone
+ * Convert a time to its human readable components in the local timezone.
* @param result the exploded time
* @param input the time to explode
*/
@@ -156,8 +156,8 @@
apr_time_t input);
/**
- * Convert time value from human readable format to a numeric apr_time_t
- * e.g. elapsed usec since epoch
+ * Convert time value from human readable format to a numeric apr_time_t
+ * (elapsed microseconds since the epoch).
* @param result the resulting imploded time
* @param input the input exploded time
*/
@@ -166,7 +166,7 @@
/**
* Convert time value from human readable format to a numeric apr_time_t that
- * always represents GMT
+ * always represents GMT.
* @param result the resulting imploded time
* @param input the input exploded time
*/
@@ -185,7 +185,7 @@
/**
* apr_rfc822_date formats dates in the RFC822
* format in an efficient manner. It is a fixed length
- * format which requires the indicated amount of storage,
+ * format which requires APR_RFC822_DATA_LEN bytes of storage,
* including the trailing NUL terminator.
* @param date_str String to write to.
* @param t the time to convert
@@ -196,18 +196,18 @@
#define APR_CTIME_LEN (25)
/**
* apr_ctime formats dates in the ctime() format
- * in an efficient manner. it is a fixed length format
- * and requires the indicated amount of storage including
+ * in an efficient manner. It is a fixed length format
+ * and requires APR_CTIME_LEN bytes of storage including
* the trailing NUL terminator.
* Unlike ANSI/ISO C ctime(), apr_ctime() does not include
- * a \n at the end of the string.
+ * a \\n at the end of the string.
* @param date_str String to write to.
* @param t the time to convert
*/
APR_DECLARE(apr_status_t) apr_ctime(char *date_str, apr_time_t t);
/**
- * formats the exploded time according to the format specified
+ * Formats the exploded time according to the format specified
* @param s string to write to
* @param retsize The length of the returned string
* @param max The maximum length of the string
@@ -220,7 +220,7 @@
/**
* Improve the clock resolution for the lifetime of the given pool.
- * Generally this is only desireable on benchmarking and other very
+ * Generally this is only desirable on benchmarking and other very
* time-sensitive applications, and has no impact on most platforms.
* @param p The pool to associate the finer clock resolution
*/
