Hi folks, During the past Apachecon, I hosted a BOF on the httpd-2.0 and apr doxygen documentation. My personal reason for calling the meeting was, that, when I was writing mod_zeroconf I found the present doxygen output to be incomplete and very hard to navigate. Also, the combined httpd and apr make dox target produces about 900 lines of warnings which is obviously suboptimal.
During the meeting (I'm not going to give a roll call because I'd forget to
include people but we had about seven participants) we had some constructive
conversation about the subject; played around with doxygen's HTML treeview
(set GENERATE_TREEVIEW=YES in doxygen.conf); floated the idea of using the
@bug tag to mark to-do's, FIXMEs and the like; agreed that the conversion
from scandoc needs to be completed and that missing documentation tags
should be added (undocumented items actually account for most of the
warnings).
Now, my company is having a two-week shutdown throug the end of the year, so
aside from some stealth ski trips I might actually have some time to sink
into this. I started with APR because it's a subset, generates 'only' 291
warnings and work on APR will carry over into the full httpd + apr
combination. The following patch picks some low hanging fruit from
apr_poll.h:
* Move the #define documentation out of their own group (which bonks them
onto a separate page) into the main apr_poll documentation
* Change the @remark of apr_poll() to be regular text rather than <pre>.
The original exposes breakage in doxygen where it can't seem to deal
with blank lines in preformatted sections
* apr_poll() returns the number of fds polled in the third argument
rather than the second: the second is passed by value.
Index: include/apr_poll.h
===================================================================
RCS file: /home/cvspublic/apr/include/apr_poll.h,v
retrieving revision 1.13
diff -u -r1.13 apr_poll.h
--- include/apr_poll.h 21 Nov 2003 19:50:02 -0000 1.13
+++ include/apr_poll.h 22 Dec 2003 04:03:51 -0000
@@ -80,8 +80,7 @@
*/
/**
- * @defgroup apr_poll_opt Poll options
- * @{
+ * Poll options
*/
#define APR_POLLIN 0x001 /**< Can read without blocking */
#define APR_POLLPRI 0x002 /**< Priority data available */
@@ -89,7 +88,6 @@
#define APR_POLLERR 0x010 /**< Pending error */
#define APR_POLLHUP 0x020 /**< Hangup occurred */
#define APR_POLLNVAL 0x040 /**< Descriptior invalid */
-/** @} */
/** Used in apr_pollfd_t to determine what the apr_descriptor is */
typedef enum {
@@ -186,13 +184,9 @@
* a maximum, not a minimum. If a socket is signalled, we
* will wake up before this time. A negative number means
* wait until a socket is signalled.
- * @remark
- * <PRE>
- * The number of sockets signalled is returned in the second argument.
- *
- * This is a blocking call, and it will not return until either a
- * socket has been signalled, or the timeout has expired.
- * </PRE>
+ * @remark The number of sockets signalled is returned in the third
argument.
+ * This is a blocking call, and it will not return until either a
+ * socket has been signalled, or the timeout has expired.
*/
APR_DECLARE(apr_status_t) apr_poll(apr_pollfd_t *aprset, apr_int32_t
numsock,
apr_int32_t *nsds,
Patch also attached. More should follow as time permits.
S.
--
[EMAIL PROTECTED] http://www.temme.net/sander/
PGP FP: 51B4 8727 466A 0BC3 69F4 B7B8 B2BE BC40 1529 24AF
apr_poll.h.patch
Description: Binary data
