Doxygen fixes
Hi,
here is a patch against APR in order to fix most of the doxygen warnings.
Note that I have updated a function prototype in apr_md5.h in order to
match the corresponding function in apr_md5.c. s/password/pw/
I have also turned some @tip into @note because @tip is not a known
keyword for doxygen.
Best regards,
CJ
Index: include/apr_dbd.h
===
--- include/apr_dbd.h (révision 1611200)
+++ include/apr_dbd.h (copie de travail)
@@ -231,7 +231,7 @@
* May be a no-op.
*
* @param driver - the driver
- * @param handle - the db connection
+ * @param pool - working pool
* @param trans - the transaction.
* @return 0 for success or error code
*/
Index: include/apr_md5.h
===
--- include/apr_md5.h (révision 1611200)
+++ include/apr_md5.h (copie de travail)
@@ -131,17 +131,17 @@
/**
* Encode a password using an MD5 algorithm
- * @param password The password to encode
+ * @param pw The password to encode
* @param salt The salt string to use for the encoding
* @param result The string to store the encoded password in
* @param nbytes The size of the result buffer
*/
-APR_DECLARE(apr_status_t) apr_md5_encode(const char *password, const char
*salt,
+APR_DECLARE(apr_status_t) apr_md5_encode(const char *pw, const char *salt,
char *result, apr_size_t nbytes);
/**
* Encode a password using the bcrypt algorithm
- * @param password The password to encode
+ * @param pw The password to encode
* @param count The cost of the encoding, possible values are 4 to 31
* @param salt Pointer to binary data to be used as salt for the encoding
* @param salt_len The size of the salt data (must be = 16)
Index: include/apr_memcache.h
===
--- include/apr_memcache.h (révision 1611200)
+++ include/apr_memcache.h (copie de travail)
@@ -370,7 +370,6 @@
* @param msserver to query
* @param p Pool to allocate answer from
* @param baton location to store server version string
- * @param len length of the server version string
*/
APR_DECLARE(apr_status_t) apr_memcache_version(apr_memcache_server_t *ms,
apr_pool_t *p,
Index: include/apr_network_io.h
===
--- include/apr_network_io.h(révision 1611200)
+++ include/apr_network_io.h(copie de travail)
@@ -750,8 +750,10 @@
apr_sockaddr_t *sockaddr);
/**
- * Write the IP address (in numeric address string format) of the APR
- * socket address @a sockaddr into the buffer @a buf (of size @a buflen).
+ * Write the IP address (in numeric address string format) of an APR
+ * socket address.
+ * @param buf The buffer to write to.
+ * @param buflen The size of the buffer.
* @param sockaddr The socket address to reference.
*/
APR_DECLARE(apr_status_t) apr_sockaddr_ip_getbuf(char *buf, apr_size_t buflen,
Index: include/apr_pools.h
===
--- include/apr_pools.h (révision 1611200)
+++ include/apr_pools.h (copie de travail)
@@ -727,7 +727,7 @@
* In this case the caller must call apr_pool_join() to indicate this
* guarantee to the APR_POOL_DEBUG code.
*
- * These functions are only implemented when #APR_POOL_DEBUG is set.
+ * These functions are only implemented when APR_POOL_DEBUG is set.
*
* @{
*/
Index: include/apr_thread_pool.h
===
--- include/apr_thread_pool.h (révision 1611200)
+++ include/apr_thread_pool.h (copie de travail)
@@ -267,7 +267,7 @@
/**
* Access function for the threshold of tasks in queue to trigger a new thread.
* @param me The thread pool
- * @param cnt The new threshold
+ * @param val The new threshold
* @return The original threshold
*/
APR_DECLARE(apr_size_t) apr_thread_pool_threshold_set(apr_thread_pool_t *me,
Index: include/arch/win32/apr_arch_utf8.h
===
--- include/arch/win32/apr_arch_utf8.h (révision 1611200)
+++ include/arch/win32/apr_arch_utf8.h (copie de travail)
@@ -30,7 +30,7 @@
* to the ucs-2 wide Unicode format. This function is used for filename and
* other resource conversions for platforms providing native Unicode support.
*
- * @tip Only the errors APR_EINVAL and APR_INCOMPLETE may occur, the former
+ * @note Only the errors APR_EINVAL and APR_INCOMPLETE may occur, the former
* when the character code is invalid (in or out of context) and the later
* when more characters were expected, but insufficient characters remain.
*/
@@ -44,7 +44,7 @@
* the utf-8 octet-encoded Unicode. This function is used for filename and
* other resource conversions for platforms providing
Re: [PATCH] doxygen fixes
Neil Conway wrote: Attached is a straightforward patch against svn trunk that fixes various doxygen usage warnings and minor errors. Committed to trunk, and backported to v1.4 and v1.3. Regards, Graham --
[PATCH] doxygen fixes
Attached is a straightforward patch against svn trunk that fixes various doxygen usage warnings and minor errors. Neil apr_dox_fixes-1.patch Description: Binary data
[PATCH] Some Doxygen fixes
While I'm procrastinating and putting off working on my Apachecon
presentation, here's an attempt at fixing some of the load that
Doxygen spews when making dox on APR:
Index: docs/doxygen.conf
===
--- docs/doxygen.conf(revision 219530)
+++ docs/doxygen.conf(working copy)
@@ -5,6 +5,7 @@
RECURSIVE=YES
FILE_PATTERNS=*.h
+EXAMPLE_PATH=docs/examples
OUTPUT_DIRECTORY=docs/dox
MACRO_EXPANSION=YES
@@ -23,6 +24,7 @@
OPTIMIZE_OUTPUT_FOR_C=YES
STRIP_CODE_COMMENTS=NO
+GENERATE_TREEVIEW=YES
FULL_PATH_NAMES=NO
CASE_SENSE_NAMES=NO
Index: include/apr.h.in
===
--- include/apr.h.in(revision 219530)
+++ include/apr.h.in(working copy)
@@ -254,21 +254,21 @@
/* Typedefs that APR needs. */
-typedef unsigned char apr_byte_t;
+typedef unsigned char apr_byte_t; /** An eight bit
unsigned integer type */
-typedef @short_value@ apr_int16_t;
-typedef unsigned @short_value@ apr_uint16_t;
+typedef @short_value@ apr_int16_t; /** A sixteen bit
signed integer type */
+typedef unsigned @short_value@ apr_uint16_t; /** A sixteen bit
unsigned integer type */
-typedef @int_value@ apr_int32_t;
-typedef unsigned @int_value@apr_uint32_t;
+typedef @int_value@ apr_int32_t; /** A thirty-two bit
signed integer type */
+typedef unsigned @int_value@apr_uint32_t; /** A thirty-two bit
unsigned integer type */
-typedef @long_value@apr_int64_t;
-typedef unsigned @long_value@ apr_uint64_t;
+typedef @long_value@apr_int64_t; /** A sixty-four bit
signed integer type */
+typedef unsigned @long_value@ apr_uint64_t; /** A sixty-four bit
unsigned integer type */
-typedef @size_t_value@ apr_size_t;
-typedef @ssize_t_value@ apr_ssize_t;
-typedef @off_t_value@ apr_off_t;
-typedef @socklen_t_value@ apr_socklen_t;
+typedef @size_t_value@ apr_size_t; /** APR type for size
parameters */
+typedef @ssize_t_value@ apr_ssize_t; /** APR type for size
difference */
+typedef @off_t_value@ apr_off_t; /** APR type for
address offset */
+typedef @socklen_t_value@ apr_socklen_t; /** Size of an
apr_sockaddr_t */
#define APR_SIZEOF_VOIDP @voidp_size@
@@ -296,9 +296,7 @@
* variable arguments must use APR_DECLARE_NONSTD().
*
* @remark Both the declaration and implementations must use the
same macro.
- * @example
- */
-/** APR_DECLARE(rettype) apr_func(args)
+ * @example APR_DECLARE.txt
* @see APR_DECLARE_NONSTD @see APR_DECLARE_DATA
* @remark Note that when APR compiles the library itself, it
passes the
* symbol -DAPR_DECLARE_EXPORT to the compiler on some platforms
(e.g. Win32)
@@ -317,10 +315,8 @@
* APR_DECLARE_NONSTD(), as they must follow the C language calling
convention.
* @see APR_DECLARE @see APR_DECLARE_DATA
* @remark Both the declaration and implementations must use the
same macro.
- * @example
+ * @example APR_DECLARE_NONSTD.txt
*/
-/** APR_DECLARE_NONSTD(rettype) apr_func(args, ...);
- */
#define APR_DECLARE_NONSTD(type) type
/**
@@ -329,11 +325,8 @@
* @see APR_DECLARE @see APR_DECLARE_NONSTD
* @remark Note that the declaration and implementations use
different forms,
* but both must include the macro.
- * @example
+ * @example APR_DECLARE_DATA.txt
*/
-/** extern APR_DECLARE_DATA type apr_variable;\n
- * APR_DECLARE_DATA type apr_variable = value;
- */
#define APR_DECLARE_DATA
/* Define APR_SSIZE_T_FMT.
Index: include/apr_thread_proc.h
===
--- include/apr_thread_proc.h(revision 219530)
+++ include/apr_thread_proc.h(working copy)
@@ -704,13 +704,13 @@
* pre
* rv = apr_proc_wait_all_procs(proc, exitcode, status,
APR_WAIT, p);
* if (APR_STATUS_IS_CHILD_DONE(rv)) {
- * #if APR_HAS_OTHER_CHILD
+ * \#if APR_HAS_OTHER_CHILD
* if (apr_proc_other_child_alert(proc, APR_OC_REASON_DEATH,
status)
* == APR_SUCCESS) {
* ; (already handled)
* }
* else
- * #endif
+ * \#endif
* [... handling non-otherchild processes death ...]
* /pre
*/
Please consider this both for content merit and doxygen-non-turdiness
merit. This patch reduces the doxygen spew from 286 lines to 265
lines on my Powerbook, tested with the latest stable doxygen (1.4.3).
Question: there's a lot more stuff in apr.h.in that shows up as non-
documented, but I assume much of it (like the #define APR_INLINE and
such) is internal and doesn't really need to be documented. Or does it?
S.
--
[EMAIL PROTECTED] http://www.temme.net/sander/
PGP FP: 51B4 8727 466A 0BC3 69F4 B7B8 B2BE BC40 1529 24AF
