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 this
Index: 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. */