svn commit: r1667599 - /subversion/branches/move-tracking-2/subversion/include/private/svn_branch.h

[ju...@apache.org]

Author: julianfoad
Date: Wed Mar 18 18:27:46 2015
New Revision: 1667599

URL: http://svn.apache.org/r1667599
Log:
On the 'move-tracking-2' branch:

* subversion/include/private/svn_branch.h
  (svn_branch_branchify): Rewrite the doc string.

Modified:
    subversion/branches/move-tracking-2/subversion/include/private/svn_branch.h

Modified: subversion/branches/move-tracking-2/subversion/include/private/svn_branch.h
URL: http://svn.apache.org/viewvc/subversion/branches/move-tracking-2/subversion/include/private/svn_branch.h?rev=1667599&r1=1667598&r2=1667599&view=diff
==============================================================================
--- subversion/branches/move-tracking-2/subversion/include/private/svn_branch.h (original)
+++ subversion/branches/move-tracking-2/subversion/include/private/svn_branch.h Wed Mar 18 18:27:46 2015
@@ -696,21 +696,31 @@ svn_branch_branch(svn_branch_instance_t
                   const char *new_name,
                   apr_pool_t *scratch_pool);
 
-/* Change the existing simple sub-tree at OUTER_BRANCH:OUTER_EID into a
- * sub-branch in a new branch family.
+/* Replace the existing simple sub-tree at OUTER_BRANCH:OUTER_EID with a
+ * new subtree that has identical content but is a sub-branch in a new
+ * branch family.
  *
- * Set *NEW_BRANCH_P to the new branch.
+ * Delete the element OUTER_BRANCH:OUTER_EID. Create a new branch family
+ * and a branch instance of it, nested in OUTER_BRANCH. Create a
+ * subbranch-root element in OUTER_BRANCH (with a new EID) at the same
+ * parent element and same name, and create child elements to match the
+ * old subtree.
  *
- * ### TODO: Also we must (in order to maintain correctness) branchify
- *     the corresponding subtrees in all other branches in this family.
+ * Note: No mapping between the old and the new elements is recorded.
  *
- * TODO: Allow adding to an existing family, by specifying a mapping.
+ * Set *NEW_BRANCH_P to the new subbranch.
  *
- *   create a new family
- *   create a new branch-def and branch-instance
- *   for each element in subtree:
- *     ?[unassign eid in outer branch (except root element)]
- *     assign a new eid in inner branch
+ * The old element at OUTER_EID must be a 'dir' or 'file' element, and not
+ * the root element of OUTER_BRANCH, and there must be no subbranch root
+ * elements below it.
+ *
+ * ### Mixes pathwise ('select a subtree') and element-wise semantics.
+ *
+ * ### Should be built from simpler operations: 'branchify' is not a
+ * fundamental operation and does not need to appear at this API level.
+ *
+ * TODO: Allow adding to an existing family, by specifying a mapping to
+ * be used during the conversion.
  */
 svn_error_t *
 svn_branch_branchify(svn_branch_instance_t **new_branch_p,