You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@subversion.apache.org by ju...@apache.org on 2012/11/07 22:53:10 UTC
svn commit: r1406833 - /subversion/trunk/subversion/include/svn_client.h
Author: julianfoad
Date: Wed Nov 7 21:53:09 2012
New Revision: 1406833
URL: http://svn.apache.org/viewvc?rev=1406833&view=rev
Log:
Fix up the doc strings of the automatic-merge public API.
* subversion/include/svn_client.h
(svn_client_automatic_merge_t,
svn_client_find_automatic_merge,
svn_client_find_automatic_merge_no_wc,
svn_client_do_automatic_merge,
svn_client_automatic_merge_is_reintegrate_like,
svn_client_automatic_merge_get_locations): Convert doc strings to Doxygen
mark-up, add missing info, remove obsolete comments, correct some
parameter names.
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=1406833&r1=1406832&r2=1406833&view=diff
==============================================================================
--- subversion/trunk/subversion/include/svn_client.h (original)
+++ subversion/trunk/subversion/include/svn_client.h Wed Nov 7 21:53:09 2012
@@ -3376,19 +3376,42 @@ svn_client_diff_summarize_peg(const char
* @{
*/
-/* Details of an automatic merge. */
+/** Details of an automatic merge.
+ *
+ * The information includes the locations of the youngest common ancestor,
+ * merge base, and such like. The details are private to the implementation
+ * but some of the information can be retrieved through the public APIs
+ * svn_client_automatic_merge_is_reintegrate_like() and
+ * svn_client_automatic_merge_get_locations().
+ *
+ * @since New in 1.8.
+ */
typedef struct svn_client_automatic_merge_t svn_client_automatic_merge_t;
-/* Find the information needed to merge all unmerged changes from a source
- * branch into a target branch. The information is the locations of the
- * youngest common ancestor, merge base, and such like.
+/** Find the information needed to merge all unmerged changes from a source
+ * branch into a target branch.
+ *
+ * Set @a *merge_p to the information needed to merge all unmerged changes
+ * (up to @a source_revision) from the source branch @a source_path_or_url
+ * at @a source_revision into the target WC at @a target_wcpath.
+ *
+ * The flags @a allow_mixed_rev, @a allow_local_mods and
+ * @a allow_switched_subtrees enable merging into a WC that is in any or all
+ * of the states described by their names, but only if this function decides
+ * that the merge will be in the same direction as the last automatic merge.
+ * If, on the other hand, the merge turns out to be in the opposite
+ * direction (that is, if svn_client_automatic_merge_is_reintegrate_like()
+ * would return true), then such states of the WC are not allowed regardless
+ * of these flags. This function merely records these flags in the
+ * @a *merge_p structure; svn_client_do_automatic_merge() checks the WC
+ * state for compliance.
*
- * Set *MERGE to the information needed to merge all unmerged changes
- * (up to SOURCE_REVISION) from the source branch SOURCE_PATH_OR_URL @
- * SOURCE_REVISION into the target WC at TARGET_WCPATH.
+ * Allocate the @a *merge_p structure in @a result_pool.
+ *
+ * @since New in 1.8.
*/
svn_error_t *
-svn_client_find_automatic_merge(svn_client_automatic_merge_t **merge,
+svn_client_find_automatic_merge(svn_client_automatic_merge_t **merge_p,
const char *source_path_or_url,
const svn_opt_revision_t *source_revision,
const char *target_wcpath,
@@ -3399,18 +3422,22 @@ svn_client_find_automatic_merge(svn_clie
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
-/* Find out what kind of automatic merge would be needed, when the target
+/** Find out what kind of automatic merge would be needed, when the target
* is only known as a repository location rather than a WC.
*
- * Like svn_client_find_automatic_merge() except that SOURCE_PATH_OR_URL @
- * SOURCE_REVISION should refer to a repository location and not a WC.
+ * Like svn_client_find_automatic_merge() except that @a source_path_or_url
+ * at @a source_revision should refer to a repository location and not a WC.
+ *
+ * @note The result, @a *merge_p, is not intended for passing to
+ * svn_client_do_automatic_merge().
+ * ### We should do something about this. Perhaps ensure
+ * svn_client_do_automatic_merge() will work iff given a WC that
+ * matches the stored repo-location of the target branch and is an
+ * unmodified single-rev WC.
+ *
+ * Allocate the @a *merge_p structure in @a result_pool.
*
- * ### The result, *MERGE_P, may not be suitable for passing to
- * svn_client_do_automatic_merge(). The target WC state would not be
- * checked (as in the ALLOW_* flags). We should resolve this problem:
- * perhaps add the allow_* params here, or provide another way of setting
- * them; and perhaps ensure __do_...() will accept the result iff given a
- * WC that matches the stored target location.
+ * @since New in 1.8.
*/
svn_error_t *
svn_client_find_automatic_merge_no_wc(
@@ -3423,19 +3450,15 @@ svn_client_find_automatic_merge_no_wc(
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
-/* Perform an automatic merge.
+/** Perform an automatic merge.
*
- * Merge according to MERGE into the WC at TARGET_WCPATH.
+ * Perform a merge, according to the information stored in @a merge, into
+ * the WC at @a target_wcpath. The @a merge structure would typically come
+ * from calling svn_client_find_automatic_merge().
*
* The other parameters are as in svn_client_merge4().
*
- * ### TODO: There's little point in this function being the only way the
- * caller can use the result of svn_client_find_automatic_merge(). The
- * contents of MERGE should be more public, or there should be other ways
- * the caller can use it, or these two functions should be combined into
- * one. I want to make it more public, and also possibly have more ways
- * to use it in future (for example, do_automatic_merge_with_step_by_-
- * step_confirmation).
+ * @since New in 1.8.
*/
svn_error_t *
svn_client_do_automatic_merge(const svn_client_automatic_merge_t *merge,
@@ -3448,22 +3471,34 @@ svn_client_do_automatic_merge(const svn_
svn_client_ctx_t *ctx,
apr_pool_t *scratch_pool);
-/* Return TRUE iff the automatic merge represented by MERGE is going to be
- * a reintegrate-like merge: that is, merging in the opposite direction
- * from the last full merge.
+/** Return TRUE iff the automatic merge represented by @a merge is going to
+ * be a reintegrate-like merge: that is, merging in the opposite direction
+ * from the last automatic merge.
*
- * This function exists because the merge is NOT really automatic and the
+ * This function exists because the automatic merge is not symmetric and the
* client can be more friendly if it knows something about the differences.
+ *
+ * @since New in 1.8.
*/
svn_boolean_t
svn_client_automatic_merge_is_reintegrate_like(
const svn_client_automatic_merge_t *merge);
-/* Set *YCA, *BASE, *RIGHT, *TARGET to the repository locations of the
- * youngest common ancestor of the branches, the base chosen for 3-way
- * merge, the right-hand side of the source diff, and the target WC.
+/** Retrieve the repository coordinates involved in an automatic merge.
*
- * Any of the output pointers may be NULL if not wanted.
+ * Set @a *yca_url, @a *yca_rev, @a *base_url, @a *base_rev, @a *right_url,
+ * @a *right_rev, @a *target_url, @a *target_rev to the repository locations
+ * of, respectively: the youngest common ancestor of the branches, the base
+ * chosen for 3-way merge, the right-hand side of the source diff, and the
+ * target WC.
+ *
+ * Set @a repos_root_url to the URL of the repository root. The four
+ * locations are necessarily in the same repository.
+ *
+ * Allocate the results in @a result_pool. Any of the output pointers may
+ * be NULL if not wanted.
+ *
+ * @since New in 1.8.
*/
svn_error_t *
svn_client_automatic_merge_get_locations(