subversion-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From julianf...@apache.org
Subject svn commit: r1406833 - /subversion/trunk/subversion/include/svn_client.h
Date Wed, 07 Nov 2012 21:53:10 GMT
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(



Mime
View raw message