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