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
