[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: Daniel Shahaf <d.s_at_daniel.shahaf.name>
Date: Wed, 22 Sep 2010 12:33:12 +0200

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?)
 * 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?)

[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)

?
Received on 2010-09-22 12:34:42 CEST

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