You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@apr.apache.org by Stas Bekman <st...@stason.org> on 2002/01/22 09:58:48 UTC
which is *arg1 in docs first or second?
Hi,
The apr apr_file_io.h header file uses arg1 to reference to an argument
of the function. It's very confusing, since it's not clear whether it
refers to the the first argument (human count) or the second (counting
from 0 in C). e.g.:
apr_file_io.h:
/**
* duplicate the specified file descriptor.
* @param new_file The structure to duplicate into.
* @param old_file The file to duplicate.
* @param p The pool to use for the new file.
* @remark *arg1 must point to a valid apr_file_t, or point to NULL
^^^^^
*/
APR_DECLARE(apr_status_t) apr_file_dup(apr_file_t **new_file,
apr_file_t *old_file,
apr_pool_t *p);
and in two more places in this file, other .h files seem not to have a
ref to arg1.
I think it's better to use the named argument in this case, e.g.
* @remark *new_file must point to a valid apr_file_t...
Thanks.
_____________________________________________________________________
Stas Bekman JAm_pH -- Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide http://perl.apache.org/guide
mailto:stas@stason.org http://ticketmaster.com http://apacheweek.com
http://singlesheaven.com http://perl.apache.org http://perlmonth.com/
Re: which is *arg1 in docs first or second?
Posted by "William A. Rowe, Jr." <wr...@covalent.net>.
From: "William A. Rowe, Jr." <wr...@covalent.net>
Sent: Tuesday, January 22, 2002 7:49 AM
> I've been looking at this since David wrote the change. The user has no
> choice is passing an apr_file_t for new_file (really dup_file). So as best
> as I can figure, this should [must?] be an apr_file_t*, not a **.
I was writing, of course, about apr_file_dup2(), which replaces that
convoluted documentation by splitting the behavior of dup() and dup2().
AFAIU, dup() will not require the apr_file_t **new to be initialized to
NULL - that is replaced by dup2() with the semantics I described above.
So with David's dup2() introduction complete across platforms (IIRC)...
> I'll change the API if I receive no objections by late this evening.
And fix the docs appropriately.
Bill
> From: "Stas Bekman" <st...@stason.org>
> Sent: Tuesday, January 22, 2002 2:58 AM
>
>
> > The apr apr_file_io.h header file uses arg1 to reference to an argument
> > of the function. It's very confusing, since it's not clear whether it
> > refers to the the first argument (human count) or the second (counting
> > from 0 in C). e.g.:
> >
> > apr_file_io.h:
> >
> > /**
> > * duplicate the specified file descriptor.
> > * @param new_file The structure to duplicate into.
> > * @param old_file The file to duplicate.
> > * @param p The pool to use for the new file.
> > * @remark *arg1 must point to a valid apr_file_t, or point to NULL
> > ^^^^^
> > */
> > APR_DECLARE(apr_status_t) apr_file_dup(apr_file_t **new_file,
> > apr_file_t *old_file,
> > apr_pool_t *p);
> >
> > and in two more places in this file, other .h files seem not to have a
> > ref to arg1.
> >
> > I think it's better to use the named argument in this case, e.g.
> >
> > * @remark *new_file must point to a valid apr_file_t...
>
>
>
>
Re: which is *arg1 in docs first or second?
Posted by "William A. Rowe, Jr." <wr...@covalent.net>.
Funny you should bring this up Stas :)
I've been looking at this since David wrote the change. The user has no
choice is passing an apr_file_t for new_file (really dup_file). So as best
as I can figure, this should [must?] be an apr_file_t*, not a **.
I'll change the API if I receive no objections by late this evening.
Bill
From: "Stas Bekman" <st...@stason.org>
Sent: Tuesday, January 22, 2002 2:58 AM
> The apr apr_file_io.h header file uses arg1 to reference to an argument
> of the function. It's very confusing, since it's not clear whether it
> refers to the the first argument (human count) or the second (counting
> from 0 in C). e.g.:
>
> apr_file_io.h:
>
> /**
> * duplicate the specified file descriptor.
> * @param new_file The structure to duplicate into.
> * @param old_file The file to duplicate.
> * @param p The pool to use for the new file.
> * @remark *arg1 must point to a valid apr_file_t, or point to NULL
> ^^^^^
> */
> APR_DECLARE(apr_status_t) apr_file_dup(apr_file_t **new_file,
> apr_file_t *old_file,
> apr_pool_t *p);
>
> and in two more places in this file, other .h files seem not to have a
> ref to arg1.
>
> I think it's better to use the named argument in this case, e.g.
>
> * @remark *new_file must point to a valid apr_file_t...