Mailing-List: contact dev-help@apr.apache.org; run by ezmlm
Precedence: bulk
Received-SPF: neutral (asf.osuosl.org: local policy)
Mime-Version: 1.0 (Apple Message framework v733)
Content-Transfer-Encoding: 7bit
Message-Id: <B2251079-FE45-4606-9FBD-B89C071DD3F2@temme.net>
Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed
To: dev@apr.apache.org
From: Sander Temme <sander@temme.net>
Subject: [PATCH] Some Doxygen fixes
Date: Tue, 19 Jul 2005 17:59:43 +0200

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.

-- 
sander@temme.net              http://www.temme.net/sander/
PGP FP: 51B4 8727 466A 0BC3 69F4  B7B8 B2BE BC40 1529 24AF