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.
*
* @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.
$0.02,
Daniel
Received on 2010-09-21 23:26:10 CEST