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 2015/10/26 11:34:13 UTC
svn commit: r1710555 - in
/subversion/branches/move-tracking-2/subversion/include/private:
svn_branch.h svn_editor3e.h
Author: julianfoad
Date: Mon Oct 26 10:34:13 2015
New Revision: 1710555
URL: http://svn.apache.org/viewvc?rev=1710555&view=rev
Log:
On the 'move-tracking-2' branch: Transfer most of the doc strings from
svn_editor3_t methods to svn_branch_txn_t and svn_branch_state_t,
updating them.
* subversion/include/svn_editor3e.h,
subversion/include/svn_branch.h
Transfer and update some doc strings. Remove old declarations that
no longer carry useful documentation.
Modified:
subversion/branches/move-tracking-2/subversion/include/private/svn_branch.h
subversion/branches/move-tracking-2/subversion/include/private/svn_editor3e.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=1710555&r1=1710554&r2=1710555&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 Mon Oct 26 10:34:13 2015
@@ -199,6 +199,26 @@ svn_branch_txn_new_eid(svn_branch_txn_t
int *new_eid_p,
apr_pool_t *scratch_pool);
+/** Create a new branch or access an existing branch.
+ *
+ * When creating a branch, declare its root element id to be ROOT_EID. Do
+ * not instantiate the root element, nor any other elements.
+ *
+ * We use a common 'open subbranch' method for both 'find' and 'add'
+ * cases, according to the principle that 'editing' a txn should dictate
+ * the new state without reference to the old state.
+ *
+ * This method returns a mutable 'branch state' object which is a part of
+ * the txn.
+ *
+ * When adding a new branch, PREDECESSOR and ROOT_EID are used.
+ *
+ * ### When opening ('finding') an existing branch, they must match it
+ * (else throw an error)? But this is problematic: we should't care
+ * exactly where it was branched from, as long as it was branched from
+ * ... roughly 'the right branch'? ... perhaps meaning one with a common
+ * ancestor?
+ */
svn_error_t *
svn_branch_txn_open_branch(svn_branch_txn_t *txn,
svn_branch_state_t **new_branch_p,
@@ -216,14 +236,35 @@ svn_branch_txn_branch(svn_branch_txn_t *
apr_pool_t *result_pool,
apr_pool_t *scratch_pool);
+/** Register a sequence point.
+ *
+ * At a sequence point, elements are arranged in a tree hierarchy: each
+ * element has exactly one parent element, except the root, and so on.
+ * Translation between paths and element addressing is defined only at
+ * a sequence point.
+ *
+ * The other edit operations -- add, alter, delete, etc. -- result in a
+ * state that is not a sequence point.
+ *
+ * The new transaction begins at a sequence point. Completion of editing
+ * (svn_branch_txn_complete()) also creates a sequence point.
+ */
svn_error_t *
svn_branch_txn_sequence_point(svn_branch_txn_t *txn,
apr_pool_t *scratch_pool);
+/** Finalize this transaction.
+ *
+ * Notify that the edit has been completed successfully.
+ */
svn_error_t *
svn_branch_txn_complete(svn_branch_txn_t *txn,
apr_pool_t *scratch_pool);
+/** Abandon this transaction.
+ *
+ * Notify that editing this transaction was not successful.
+ */
svn_error_t *
svn_branch_txn_abort(svn_branch_txn_t *txn,
apr_pool_t *scratch_pool);
@@ -488,16 +529,68 @@ svn_element_content_t *
svn_branch_get_element(const svn_branch_state_t *branch,
int eid);
-/* In BRANCH, delete element EID.
+/** Specify that the element of @a branch identified by @a eid shall not
+ * be present.
+ *
+ * The delete is not explicitly recursive. However, as an effect of the
+ * final 'flattening' of a branch state into a single tree, each element
+ * in the final state that still has this element as its parent will also
+ * be deleted, recursively.
+ *
+ * The element @a eid must not be the root element of @a branch.
+ *
+ * ### Options for Out-Of-Date Checking on Rebase
+ *
+ * We may want to specify what kind of OOD check takes place. The
+ * following two options differ in what happens to an element that is
+ * added, on the other side, as a child of this deleted element.
+ *
+ * Rebase option 1: The rebase checks for changes in the whole subtree,
+ * excluding any portions of the subtree for which an explicit delete or
+ * move-away has been issued. The check includes checking that the other
+ * side has not added any child. In other words, the deletion is
+ * interpreted as an action affecting a subtree (dynamically rooted at
+ * this element), rather than as an action affecting a single element or
+ * a fixed set of elements that was explicitly or implicitly specified
+ * by the sender.
+ *
+ * To delete a mixed-rev subtree, the client sends an explicit delete for
+ * each subtree that has a different base revision from its parent.
+ *
+ * Rebase option 2: The rebase checks for changes to this element only.
+ * The sender can send an explicit delete for each existing child element
+ * that it requires to be checked as well. However, there is no way for
+ * the sender to specify whether a child element added by the other side
+ * should be considered an out-of-date error or silently deleted.
+ *
+ * It would also be possible to let the caller specify, at some suitable
+ * granularity, which option to use.
*/
svn_error_t *
svn_branch_state_delete_one(svn_branch_state_t *branch,
svn_branch_eid_t eid,
apr_pool_t *scratch_pool);
-/* Set or change the EID:element mapping for EID in BRANCH.
+/** Specify the tree position and payload of the element of @a branch
+ * identified by @a eid.
+ *
+ * Set the element's parent EID, name and payload to @a new_parent_eid,
+ * @a new_name and @a new_payload respectively.
+ *
+ * This may create a new element or alter an existing element.
+ *
+ * If the element ... we can describe the effect as ...
+ *
+ * exists in the branch => altering it;
+ * previously existed in the branch => resurrecting it;
+ * only existed in other branches => branching it;
+ * never existed anywhere => creating or adding it.
+ *
+ * However, these are imprecise descriptions and not mutually exclusive.
+ * For example, if it existed previously in this branch and another, then
+ * we may describe the result as 'resurrecting' and/or as 'branching'.
*
- * Duplicate NEW_NAME and NEW_PAYLOAD into the branch mapping's pool.
+ * Duplicate @a new_name and @a new_payload into the branch's pool.
*/
svn_error_t *
svn_branch_state_alter_one(svn_branch_state_t *branch,
Modified: subversion/branches/move-tracking-2/subversion/include/private/svn_editor3e.h
URL: http://svn.apache.org/viewvc/subversion/branches/move-tracking-2/subversion/include/private/svn_editor3e.h?rev=1710555&r1=1710554&r2=1710555&view=diff
==============================================================================
--- subversion/branches/move-tracking-2/subversion/include/private/svn_editor3e.h (original)
+++ subversion/branches/move-tracking-2/subversion/include/private/svn_editor3e.h Mon Oct 26 10:34:13 2015
@@ -493,24 +493,11 @@ extern "C" {
/*#define SVN_EDITOR3_WITH_COPY_FROM_THIS_REV*/
-/**
- * @defgroup svn_editor The editor interface
- * @{
- */
-
/** Tree Editor
*/
typedef struct svn_editor3_t svn_editor3_t;
-/** These functions are called by the tree delta driver to edit the target.
- *
- * @see #svn_editor3_t
- *
- * @defgroup svn_editor3_drive Driving the editor
- * @{
- */
-
/*
* ========================================================================
* Editor for Commit (independent per-element changes; element-id addressing)
@@ -576,92 +563,11 @@ typedef struct svn_editor3_t svn_editor3
* but in that case the caller would need to specify the new eids.]
*/
-/** Allocate a new EID.
- */
-svn_error_t *
-svn_editor3_new_eid(svn_editor3_t *editor,
- svn_branch_eid_t *eid_p);
-
-/** Create a new branch or access an existing branch.
- *
- * When creating a branch, declare its root element id to be ROOT_EID. Do
- * not instantiate the root element, nor any other elements.
- *
- * We use a common 'open subbranch' method for both 'find' and 'add'
- * cases, according to the principle that the editor dictates the new
- * state without reference to the old state.
- *
- * This must be used before editing the resulting branch. In that sense
- * this method conceptually returns a "branch editor" for the designated
- * branch.
- *
- * When adding a new branch, PREDECESSOR and ROOT_EID are used; when
- * finding an existing branch they must match it (else throw an error).
- *
- * ### Should we take a single branch-id parameter instead of taking
- * (outer-bid, outer-eid) and returning the new branch-id?
- *
- * If we want to think of this as a "txn editor" method and we want
- * random access to any branch, that would be a good option.
- *
- * If we want to think of this as a "branch editor" method then
- * outer-branch-id conceptually identifies "this branch" that we're
- * editing and could be represented instead by a different value of
- * the "editor" parameter; and the subbranch must be an immediate child.
- */
-svn_error_t *
-svn_editor3_open_branch(svn_editor3_t *editor,
- const char **new_branch_id_p,
- svn_branch_rev_bid_t *predecessor,
- const char *outer_branch_id,
- int outer_eid,
- int root_eid,
- apr_pool_t *result_pool);
-svn_error_t *
-svn_editor3_branch(svn_editor3_t *editor,
- const char **new_branch_id_p,
- svn_branch_rev_bid_eid_t *from,
- const char *outer_branch_id,
- int outer_eid,
- apr_pool_t *result_pool);
-
-/** Specify the tree position and payload of the element of @a branch_id
- * identified by @a eid.
- *
- * This may create a new element or alter an existing element.
- *
- * Set the element's parent and name to @a new_parent_eid and @a new_name.
- *
- * Set the payload to @a new_payload. If @a new_payload is null, create a
- * subbranch-root element instead of a normal element.
+/** On serializing an edit drive over a network:
*
* A no-op change MUST be accepted but, in the interest of efficiency,
* SHOULD NOT be sent.
- *
- * @see #svn_editor3_t
- *
- * If the element ... we can describe the effect as ...
- *
- * exists in the branch => altering it;
- * previously existed in the branch => resurrecting it;
- * only existed in other branches => branching it;
- * never existed anywhere => creating or adding it.
- *
- * However, these are imprecise descriptions and not mutually exclusive.
- * For example, if it existed previously in this branch and another, then
- * we may describe the result as 'resurrecting' and/or as 'branching'.
- *
- * ### When converting this edit to an Ev1 edit, do we need a way to specify
- * where the Ev1 node is to be "copied" from, when this is branching the
- * element?
*/
-svn_error_t *
-svn_editor3_alter(svn_editor3_t *editor,
- const char *branch_id,
- svn_branch_eid_t eid,
- svn_branch_eid_t new_parent_eid,
- const char *new_name,
- const svn_element_payload_t *new_payload);
/** Create a new element that is copied from a pre-existing
* <SVN_EDITOR3_WITH_COPY_FROM_THIS_REV> or newly created </>
@@ -736,86 +642,11 @@ svn_editor3_copy_tree(svn_editor3_t *edi
svn_branch_eid_t new_parent_eid,
const char *new_name);
-/** Delete the existing element of @a branch_id identified by @a eid.
- *
- * The delete is not explicitly recursive. However, unless otherwise
- * specified, the caller may assume that each element that has element
- * @a eid as its parent in the final state will also be deleted,
- * recursively.
- *
- * If the element @a eid is a subbranch root, then delete that subbranch
- * (recursively). The element @a eid is not the root element of @a branch_id.
- *
- * ### Options for Out-Of-Date Checking on Rebase
- *
- * We may want to specify what kind of OOD check takes place. The
- * following two options differ in what happens to an element that is
- * added, on the other side, as a child of this deleted element.
- *
- * Rebase option 1: The rebase checks for changes in the whole subtree,
- * excluding any portions of the subtree for which an explicit delete or
- * move-away has been issued. The check includes checking that the other
- * side has not added any child. In other words, the deletion is
- * interpreted as an action affecting a subtree (dynamically rooted at
- * this element), rather than as an action affecting a single element or
- * a fixed set of elements that was explicitly or implicitly specified
- * by the sender.
- *
- * To delete a mixed-rev subtree, the client sends an explicit delete for
- * each subtree that has a different base revision from its parent.
- *
- * Rebase option 2: The rebase checks for changes to this element only.
- * The sender can send an explicit delete for each existing child element
- * that it requires to be checked as well. However, there is no way for
- * the sender to specify whether a child element added by the other side
- * should be considered an out-of-date error or silently deleted.
- *
- * It would also be possible to let the caller specify, per delete call,
- * which option to use.
- *
- * @see #svn_editor3_t
- */
-svn_error_t *
-svn_editor3_delete(svn_editor3_t *editor,
- const char *branch_id,
- svn_branch_eid_t eid);
-
-/** Register a sequence point.
+/** On 'flattening' with nested branching:
*
- * At a sequence point, elements are arranged in a tree hierarchy: each
- * element has exactly one parent element, except the root, and so on.
- * Translation between paths and element addressing is defined only at
- * a sequence point.
- *
- * The other edit operations -- add, alter, delete, etc. -- result in a
- * state that is not a sequence point.
- *
- * The beginning of an edit is a sequence point. Completion of an edit
- * (svn_editor3_complete()) creates a sequence point.
+ * Deleting a subbranch root element implies also deleting the subbranch
+ * it points to, recursively.
*/
-svn_error_t *
-svn_editor3_sequence_point(svn_editor3_t *editor);
-
-/** Drive @a editor's #svn_editor3_cb_complete_t callback.
- *
- * Send word that the edit has been completed successfully.
- *
- * @see #svn_editor3_t
- */
-svn_error_t *
-svn_editor3_complete(svn_editor3_t *editor);
-
-/** Drive @a editor's #svn_editor3_cb_abort_t callback.
- *
- * Notify that the edit transmission was not successful.
- * ### TODO @todo Shouldn't we add a reason-for-aborting argument?
- *
- * @see #svn_editor3_t
- */
-svn_error_t *
-svn_editor3_abort(svn_editor3_t *editor);
-
-/** @} */
#ifdef __cplusplus