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

[Julian Foad <ju...@btopenworld.com>]

Garrett Rooney wrote:
> On 2/13/06, Julian Foad <ju...@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

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

[Garrett Rooney <ro...@electricjellyfish.net>]

On 2/13/06, Julian Foad <ju...@btopenworld.com> wrote:
> Garrett Rooney wrote:
> > On 2/13/06, Julian Foad <ju...@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() ?

Well, that could certainly be done, but historically it doesn't seem
to happen very often.

> >>(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:

I'll look at getting these dealt with, thanks.

-garrett

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org