Garrett Rooney wrote:
> On 2/13/06, Julian Foad <julianfoad@btopenworld.com> wrote:
>
>>It would make sense for mainstream APR to revise this API, adding the pool
>>parameter. Do you know if IBM has proposed that to the APR developers (or are
>>likely to)? Not that we will be able to rely on it for a long time yet, but it
>>should happen anyway.
>
> No, they have not proposed it, and even if we wanted to change it we
> can't do so until APR 2.0.
Is there no API revision mechanism, like in Subversion we would introduce
apr_poll2() and deprecate apr_poll() ?
>>(If anyone wants a (miserable) laugh, take a look at the doc string for
>>apr_wait_for_io_or_timeout():
>
> Ha. That is amusing. Will fix.
Oh, thanks, Garrett; I was just starting to subscribe to the APR mailing list
in order to post a note about this and a couple of other lesser doc string
improvements that I've noted recently. If you're in the mood for it, this is
what I was going to send:
Index: apr/include/apr_getopt.h
===================================================================
--- apr/include/apr_getopt.h (revision 128444)
+++ apr/include/apr_getopt.h (working copy)
@@ -34,7 +34,8 @@
*/
/**
- * defintion of a error function
+ * An error function.
+ * ### What are the parameters, especially "arg"?
*/
typedef void (apr_getopt_err_fn_t)(void *arg, const char *err, ...);
@@ -94,8 +95,8 @@
* @param cont The pool to operate on
* @param argc The number of arguments to parse
* @param argv The array of arguments to parse
- * @remark Arguments 2 and 3 are most commonly argc and argv from main(argc, argv)
- * The errfn is initialized to fprintf(stderr... but may be overridden.
+ * @remark Arguments 3 and 4 are most commonly argc and argv from main(argc, argv)
+ * (*os)->errfn is initialized to fprintf(stderr... but may be overridden.
*/
APR_DECLARE(apr_status_t) apr_getopt_init(apr_getopt_t **os, apr_pool_t *cont,
int argc, const char * const *argv);
Index: apr/include/apr_poll.h
===================================================================
--- apr/include/apr_poll.h (revision 128444)
+++ apr/include/apr_poll.h (working copy)
@@ -151,7 +151,7 @@
* Poll the sockets in the poll structure
* @param aprset The poll structure we will be using.
* @param numsock The number of sockets we are polling
- * @param nsds The number of sockets signalled.
+ * @param nsds The number of sockets signalled (output parameter)
* @param timeout The amount of time in microseconds to wait. This is
* a maximum, not a minimum. If a socket is signalled, we
* will wake up before this time. A negative number means
Index: apr/include/apr_support.h
===================================================================
--- apr/include/apr_support.h (revision 128444)
+++ apr/include/apr_support.h (working copy)
@@ -38,7 +38,8 @@
/**
* Wait for IO to occur or timeout.
*
- * Uses POOL for temporary allocations.
+ * ### What IO? What timeout? On return, does it indicate which happened?
+ * ### What are the arguments? Shouldn't it take a pool argument?
*/
apr_status_t apr_wait_for_io_or_timeout(apr_file_t *f, apr_socket_t *s,
int for_read);
Thanks.
- Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Mon Feb 13 23:46:01 2006