Add comments and questions about WC entries.* subversion/include/svn_wc.h (svn_wc_entry_t): * subversion/libsvn_wc/entries.c (fold_scheduling): * subversion/libsvn_wc/entries.h (SVN_WC__ENTRY_MODIFY_FORCE): Write a proper doc string. (svn_wc__entry_modify): Add more info to the doc string.* subversion/libsvn_wc/update_editor.c (edit_baton): Add more info to the doc string of a field.--This line, and those below, will be ignored--Index: subversion/include/svn_wc.h===================================================================--- subversion/include/svn_wc.h (revision 34620)+++ subversion/include/svn_wc.h (working copy)@@ -1985,6 +1985,7 @@ typedef struct svn_wc_entry_t /** in a copied state (possibly because the entry is a child of a * path that is @c svn_wc_schedule_add or @c svn_wc_schedule_replace, * when the entry itself is @c svn_wc_schedule_normal) */+ /** ### How is this related to (copyfrom_url != NULL)? */ svn_boolean_t copied; /** The directory containing this entry had a versioned child of thisIndex: subversion/libsvn_wc/entries.c===================================================================--- subversion/libsvn_wc/entries.c (revision 34622)+++ subversion/libsvn_wc/entries.c (working copy)@@ -2617,13 +2617,21 @@ svn_wc__entry_remove(apr_hash_t *entries }-/* Our general purpose intelligence module for handling scheduling- changes to a single entry.+/* Our general purpose intelligence module for handling a scheduling+ change to a single entry.+ ### Determine the entry's new schedule, assuming both the base and the+ working version are being changed in the way indicated by the incoming+ "schedule".+ ### Determine the entry's new schedule, assuming the base is unchanged+ and the working version is being changed in the way indicated by the incoming "schedule". Given an entryname NAME in ENTRIES, examine the caller's requested- change in *SCHEDULE and the current state of the entry. Possibly- modify *SCHEDULE and *MODIFY_FLAGS so that when merged, it will- reflect the caller's original intent.+ scheduling change in *SCHEDULE and the current state of the entry.+ *MODIFY_FLAGS should have the 'SCHEDULE' flag set (else do nothing) and+ may have the 'FORCE' flag set (in which case do nothing).+ Determine the final schedule for the entry. To reflect this, possibly do+ any or all of: delete the entry from *ENTRIES, change *SCHEDULE to the+ new schedule, remove the 'SCHEDULE' change flag from *MODIFY_FLAGS. POOL is used for local allocations only, calling this function does not use POOL to allocate any memory referenced by ENTRIES.@@ -2740,6 +2748,8 @@ fold_scheduling(apr_hash_t *entries, case svn_wc_schedule_add: case svn_wc_schedule_replace: /* These are all no-op cases. Normal is obvious, as is add.+ ### The 'add' case is not obvious: above, we throw an error if+ ### already versioned, so why not here too? Replace on an entry marked for addition breaks down to (add + (delete + add)), which resolves to just (add), and since this entry is already marked with (add), this too@@ -2752,6 +2762,8 @@ fold_scheduling(apr_hash_t *entries, /* Not-yet-versioned item being deleted. If the original entry was not marked as "deleted", then remove the entry. Else, return the entry to a 'normal' state, preserving+ ### What does it mean for an entry be schedule-add and+ ### deleted at once, and why change schedule to normal? the "deleted" flag. Check that we are not trying to remove the SVN_WC_ENTRY_THIS_DIR entry as that would leave the entries file in an invalid state. */Index: subversion/libsvn_wc/entries.h===================================================================--- subversion/libsvn_wc/entries.h (revision 34620)+++ subversion/libsvn_wc/entries.h (working copy)@@ -165,16 +165,18 @@ svn_error_t *svn_wc__atts_to_entry(svn_w #define SVN_WC__ENTRY_MODIFY_FILE_EXTERNAL APR_INT64_C(0x0000000400000000) /* No #define for DEPTH, because it's only meaningful on this-dir anyway. */-/* ...ORed together with this to mean "I really mean this, don't be- trying to protect me from myself on this one." */+/* ...ORed together with this to mean: just set the schedule to the new+ value, instead of treating the new value as a change of state to be+ merged with the current schedule. */ #define SVN_WC__ENTRY_MODIFY_FORCE APR_INT64_C(0x4000000000000000) /* Modify an entry for NAME in access baton ADM_ACCESS by folding in ("merging") changes, and sync those changes to disk. New values for the entry are pulled from their respective fields in ENTRY, and- MODIFY_FLAGS is a bitmask to specify which of those field to pay- attention to. ADM_ACCESS must hold a write lock.+ MODIFY_FLAGS is a bitmask to specify which of those fields to pay+ attention to, formed from the values SVN_WC__ENTRY_MODIFY_....+ ADM_ACCESS must hold a write lock. NAME can be NULL to specify that the caller wishes to modify the "this dir" entry in ADM_ACCESS.@@ -185,6 +187,15 @@ svn_error_t *svn_wc__atts_to_entry(svn_w is no subsequent svn_wc__entries_write call the modifications will be lost when the access baton is closed.+ "Folding in" a change means, in most cases, simply replacing the field+ with the new value. However, for the "schedule" field, unless+ MODIFY_FLAGS includes SVN_WC__ENTRY_MODIFY_FORCE (in which case just take+ the new schedule from ENTRY), it means to determine the schedule that the+ entry should end up with if the "schedule" value from ENTRY represents a+ change/add/delete/replace being made to the+ ### base / working / base and working version(s) ?+ of the node.+ Perform all allocations in POOL. NOTE: when you call this function, the entries file will be read,Index: subversion/libsvn_wc/update_editor.c===================================================================--- subversion/libsvn_wc/update_editor.c (revision 34620)+++ subversion/libsvn_wc/update_editor.c (working copy)@@ -183,7 +183,8 @@ struct edit_baton /* Allow unversioned obstructions when adding a path. */ svn_boolean_t allow_unver_obstructions;- /* Non-null if this is a 'switch' operation. */+ /* The target URL of ###(what level of) the switch, if this is a 'switch'+ operation, else NULL. */ const char *switch_url; /* The URL to the root of the repository, or NULL. */