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

Re: svn commit: r998296 - /subversion/trunk/subversion/include/svn_client.h

From: Hyrum Wright <hwright_at_apache.org>
Date: Tue, 21 Sep 2010 22:48:43 +0100

On Tue, Sep 21, 2010 at 10:25 PM, Daniel Shahaf <d.s_at_daniel.shahaf.name> wrote:
> hwright_at_apache.org wrote on Fri, Sep 17, 2010 at 20:04:53 -0000:
>> Author: hwright
>> Date: Fri Sep 17 20:04:53 2010
>> New Revision: 998296
>>
>> URL: http://svn.apache.org/viewvc?rev=998296&view=rev
>> Log:
>> * subversion/include/svn_client.h
>>   (svn_client_cat2): Rewrite docstring (see r997639).
>>
>> Modified:
>>     subversion/trunk/subversion/include/svn_client.h
>>
>> Modified: subversion/trunk/subversion/include/svn_client.h
>> URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/include/svn_client.h?rev=998296&r1=998295&r2=998296&view=diff
>> ==============================================================================
>> --- subversion/trunk/subversion/include/svn_client.h (original)
>> +++ subversion/trunk/subversion/include/svn_client.h Fri Sep 17 20:04:53 2010
>> @@ -322,6 +322,10 @@ svn_client_get_ssl_client_cert_pw_prompt
>>   *
>>   * A brief word on operative and peg revisions.
>>   *
>> + * If the kind of the peg revision is #svn_opt_revision_unspecified, then it
>> + * defaults to #svn_opt_revision_head for URLs and #svn_opt_revision_working
>> + * for local paths.
>> + *
>>   * For deeper insight, please see the
>>   * <a href="http://svnbook.red-bean.com/nightly/en/svn.advanced.pegrevs.html">
>>   * Peg and Operative Revisions</a> section of the Subversion Book.
>> @@ -4687,26 +4691,30 @@ svn_client_ls(apr_hash_t **dirents,
>>   */
>>
>>  /**
>> - * Output the content of file identified by @a path_or_url and @a
>> - * revision to the stream @a out.  The actual node revision selected
>> - * is determined by the path as it exists in @a peg_revision.  If @a
>> - * peg_revision->kind is #svn_opt_revision_unspecified, then it defaults
>> - * to #svn_opt_revision_head for URLs or #svn_opt_revision_working
>> - * for WC targets.
>> - *
>> - * If @a path_or_url is not a local path, then if @a revision is of
>> - * kind #svn_opt_revision_previous (or some other kind that requires
>> - * a local path), an error will be returned, because the desired
>> - * revision cannot be determined.
>> - *
>> - * Use the authentication baton cached in @a ctx to authenticate against the
>> - * repository.
>> + * Output the content of a file.
>> + *
>> + * @param[in] out           The stream to which the content will be written.
>> + * @param[in] path_or_url   The path or URL of the file.
>> + * @param[in] peg_revision  The peg revision.
>> + * @param[in] revision  The operative revision.
>> + * @param[in] ctx   The standard client context, used for possible
>> + *                  authentication.
>> + * @param[in] pool  Used for any temporary allocation.
>>   *
>> - * Perform all allocations from @a pool.
>
> Sorry, but I like the old style better.  I could read it and actually
> understand what the function does; whereas text like
>
>  * Output the content of a file.

This is *exactly* what the function does, without all the extra fluff.
 Everything else is just modifying behavior, several pieces of which
are common to many of our APIs, and so should have that documentation
extracted and linked to. I'm just trying to save the effort of
reading five paragraphs of prose to find out what a single boolean
argument does.

The other problem is that the prose can make it hard to pick up on
inconsistent behavior, when something (such as depth defaults) isn't
the same between APIs.

>  *
>  * @param[in] out           The stream to which the content will be written.
>  * @param[in] path_or_url   The path or URL of the file.
>  * @param[in] peg_revision  The peg revision.
>
> tells me virtually nothing more than the signature does.

That being said, improvements are welcome, or we can just revert what
I've already done.

-Hyrum
Received on 2010-09-21 23:49:24 CEST

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