On Wed, Sep 22, 2010 at 11:33 AM, Daniel Shahaf <d.s_at_daniel.shahaf.name> wrote:
> And another stab:
>
> /**
> * Checkout a working copy from a repository.
> *
> * @param[out] result_rev
> * If non-NULL, the value of the revision checked out form
> * the repository [1]. (Useful when @a revision is of
> * a kind other than #svn_opt_revision_number.)
> * @param[in] URL The URL to checkout.
> * @param[in] peg_revision The revision to look up URL at.
> * @param[in] revision The revision of (URL,peg) to checkout. [2]
> * @param[in] path Where to create the new working copy.
> * @param[in] depth
> * Controls how many levels of file hierarchy to populate
> * in the new working copy. If #svn_depth_unknown,
> * then behave as for #svn_depth_infinity, except in the case
> * of resuming a previous checkout of @a path (i.e., updating),
> * in which case use the depth of the existing working copy.
> * @param[in] ignore_externals
> * If @c TRUE, don't process externals definitions as part
> * of this operation.
> * @see SVN_PROP_EXTERNALS
> * @param[in] allow_unver_obstructions
> * If @c TRUE, then tolerate existing
> * unversioned items that obstruct incoming paths. Only
> * obstructions of the same type (file or dir) as the added
> * item are tolerated. The text of obstructing files is left
> * as-is, effectively treating it as a user modification after
> * the checkout. Working properties of obstructing items are
> * set equal to the base properties. <br>
> (huh? "working props"? "base props"? come again?)
This is copied directly from the previous docstring. My hope is that
the new format helps us highlight (and fix) deficiencies such as this
one.
> * If @c FALSE, then raise an error if there are any unversioned
> * obstructing items.
> * @param[in] ctx
> * The standard client context, used for authentication and
> * notification.
> *
> * @return A pointer to an #svn_error_t of the type (this list is not
> * exhaustive): <br>
> * #SVN_ERR_UNSUPPORTED_FEATURE if @a URL refers to a file rather
> * than a directory; <br>
> * #SVN_ERR_RA_ILLEGAL_URL if @a URL does not exist; <br>
> * #SVN_ERR_CLIENT_BAD_REVISION if @a revision is not one of
> * #svn_opt_revision_number, #svn_opt_revision_head, or
> * #svn_opt_revision_date. <br>
> * If no error occurred, return #SVN_NO_ERROR.
> *
> * @since New in 1.5.
> *
> * @see #svn_depth_t <br> #svn_client_ctx_t <br> @ref clnt_revisions for
> * a discussion of operative and peg revisions.
> */
> svn_error_t *
> svn_client_checkout3(svn_revnum_t *result_rev,
> const char *URL,
> const char *path,
> const svn_opt_revision_t *peg_revision,
> const svn_opt_revision_t *revision,
> svn_depth_t depth,
> svn_boolean_t ignore_externals,
> svn_boolean_t allow_unver_obstructions,
> svn_client_ctx_t *ctx,
> apr_pool_t *scratch_pool);
>
> [1] For the [out] parameter, can we have @param[out,optional] and
> @param[out,mandatory] notations, or do we have to say "may be NULL"
> in the prose?)
@param[out] is part of the doxygen markup (not just some arbitrary
notation). I don't know what it would do in the face of extra values
(see http://www.stack.nl/~dimitri/doxygen/commands.html#cmdparam)
>
> [2] How about introducing:
>
> struct svn_ra_node_t {
> const char *repos_relpath;
> svn_revnum_t peg;
> };
>
> struct svn_client_node_t {
> const char *path_or_URL;
> svn_opt_revision_t *peg;
> };
>
> (that will also help make the docstrings clearer)
You'd probably want to the revision in there too, much like we do for
svn_client_copy_source_t. Both the peg revision and the operative
revision are used to specify a node (though in the absence of one, the
default is generally the other, I think).
-Hyrum
Received on 2010-09-22 13:09:37 CEST