Ev2 - tinkering with the rules docco

Some thoughts on how part of the Ev2 documentation maybe should be.  I'm not confident enough to commit this; I'm not sure it makes much more sense with this amendment that without it.  Any comments?

Index: subversion/include/svn_editor.h
===================================================================
  * In order to reduce complexity of callback receivers, the editor
  * callbacks must be driven in adherence to these rules:
- *
- * - If any path is added (with add_*) or deleted/moved/rotated, then
- *   an svn_editor_alter_directory() call must be made for its parent
- *   directory with the target/eventual set of children.
- *
- *- * - svn_editor_add_directory() -- Another svn_editor_add_*() call
- *   must follow for each child mentioned in the @a children argument
- *   of any svn_editor_add_directory() call.
- *
- * - For each node created with add_*, if its parent was created using
- *   svn_editor_add_directory(), then the new child node MUST have been
- *   mentioned in the @a children parameter of the parent's creation.
- *   This allows the parent directory to properly mark the child as
- *   "incomplete" until the child's add_* call arrives.
+ *
+ * - If the set of names of children of any directory is being changed,
+ *   then an svn_editor_alter_directory() call must be made with the
+ *   target/eventual set of children.
+ *
+ * - If a @a children argument of an add_directory or alter_directory
+ *   adds any child names that not were previously children of the
+ *   directory, an add_* or copy-here or move-here must follow for
+ *   each such child.
+ *
+ * - If a non-null @a children argument of an alter_directory omits
+ *   any child names that were previously children of the directory,
+ *   a delete or move-away must follow for each such child.
  *
  * - A path should never be referenced more than once by the
- *   add_*, alter_*, and delete
+ *   add_*, alter_*, delete and move-away
  *   operations (the "Once Rule").  The source path of a copy (and
  *   its children, if a directory) may be copied many times, and are

  *   otherwise subject to the Once Rule. The destination path of a
- *   copy or move
+ *   copy or move or rotate
  *   may have alter_* operations applied, but not
- *   add_* or delete.

+ *   add_* or delete or move-away.
  *   If the destination path of a copy, move, or rotate is a directory,
  *   then its children are subject to the Once Rule. The source path of
  *   a move (and its child paths) may be referenced in add_*, or as the
- *   destination of a copy
+ *   destination of a copy or move
  *   (where these new or copied nodes are subject to the Once Rule);
+ *   the path of a delete may not (see later rule).
  *   Paths listed in a rotation are both sources and
  *   destinations, so they may not be referenced again in an
- *   add_* or a deletion;
+ *   add_* or a delete or a move-away;
  *   these paths may have alter_* operations applied.
+ *
+ *   First op           Subsequent ops allowed
+ *   -------------      ----------------------
+ *   add_directory      (none)
+ *   add_file           (none)
+ *   add_symlink        (none)
+ *   add_absent         (none)
+ *   alter_directory    (none)
+ *   alter_file         (none)
+ *   alter_symlink      (none)
+ *   delete             add_*, copy-here, move-here (Once)
+ *   move-away
+ *   move-here          alter_(same kind)
+ *   copy-here          alter_(same kind)
+ *   rotate             alter_(same kind)
  *
  * - The ancestor of an added, copied-here, moved-here, rotated, or
  *   modified node may not be deleted. The ancestor may not be moved

- Julian

--
Certified & Supported Apache Subversion Downloads: http://www.wandisco.com/subversion/download