[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

APR APIs and their doc strings [was: [PATCH] #3 Update on port to OS400/EBCDIC]

From: Julian Foad <julianfoad_at_btopenworld.com>
Date: 2006-02-13 23:45:25 CET

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

This is an archived mail posted to the Subversion Dev mailing list.

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.