[prev in list] [next in list] [prev in thread] [next in thread] 

List:       subversion-dev
Subject:    Re: [PATCH] Correct documentation for svn_repos_node_editor and friends
From:       Erik Johansson <erik () ejohansson ! se>
Date:       2010-12-29 11:00:37
Message-ID: AANLkTimPcE6H16HnbAxb7kRCxJXO_3NZ-FSrUdzLwtpw () mail ! gmail ! com
[Download RAW message or body]

On Mon, Dec 13, 2010 at 21:35, Erik Johansson <erik@ejohansson.se> wrote:
> An attempt to untangle the mess discussed in
> http://svn.haxx.se/dev/archive-2010-12/0258.shtml

Take 2. I have tried to update the documentation according to the
comments to the previous patch. Please let me know what you think.

// Erik

[[[
Update the documentation for svn_repos_node_editor and friends to
mention all drivers that can be used to drive the editor.

As r846201 added svn_repos_replay as a "replacement not so much
for svn_repos_dir_delta, but for at least a whole class of
functionality that svn_repos_dir_delta was never intended to
handle." also add a note that svn_repos_replay2 is the preferred
driver.

* subversion/include/svn_repos.h
 (svn_repos_node_editor, svn_repos_node_from_baton): Doc update
]]]

-- 
Erik Johansson
Home Page: http://ejohansson.se/
PGP Key: http://ejohansson.se/erik.asc

["svn_repos_docs_v2.patch" (text/x-patch)]

Index: subversion/include/svn_repos.h
===================================================================
--- subversion/include/svn_repos.h	(revision 1053590)
+++ subversion/include/svn_repos.h	(working copy)
@@ -2235,20 +2235,20 @@
 /* ---------------------------------------------------------------*/
 
 /**
- * @defgroup svn_repos_inspection Data structures and editor things for
+ * @defgroup svn_repos_inspection Data structures and editor things for \
  * repository inspection.
  * @{
  *
- * As it turns out, the svn_repos_dir_delta2() interface can be
- * extremely useful for examining the repository, or more exactly,
- * changes to the repository.  svn_repos_dir_delta2() allows for
- * differences between two trees to be described using an editor.
+ * As it turns out, the svn_repos_replay2(), svn_repos_dir_delta2() and
+ * svn_repos_begin_report2() interfaces can be extremely useful for
+ * examining the repository, or more exactly, changes to the repository.
+ * These drivers allows for differences between two trees to be
+ * described using an editor.
  *
- * By using the editor obtained from svn_repos_node_editor() with
- * svn_repos_dir_delta2(), the description of how to transform one tree
- * into another can be used to build an in-memory linked-list tree,
- * which each node representing a repository node that was changed as a
- * result of having svn_repos_dir_delta2() drive that editor.
+ * By using the editor obtained from svn_repos_node_editor() with one of
+ * the drivers mentioned above, the description of how to transform one
+ * tree into another can be used to build an in-memory linked-list tree,
+ * which each node representing a repository node that was changed.
  */
 
 /** A node in the repository. */
@@ -2288,10 +2288,14 @@
 
 
 /** Set @a *editor and @a *edit_baton to an editor that, when driven by
- * svn_repos_dir_delta2(), builds an <tt>svn_repos_node_t *</tt> tree
- * representing the delta from @a base_root to @a root in @a repos's
- * filesystem.
+ * a driver such as svn_repos_replay2(), builds an <tt>svn_repos_node_t
+ * *</tt> tree representing the delta from @a base_root to @a root in @a
+ * repos's filesystem.
  *
+ * The editor can also be driven by svn_repos_dir_delta2() or
+ * svn_repos_begin_report2(), but unless you have special needs,
+ * svn_repos_replay2() is preferred.
+ *
  * Invoke svn_repos_node_from_baton() on @a edit_baton to obtain the root
  * node afterwards.
  *
@@ -2311,9 +2315,9 @@
                       apr_pool_t *pool);
 
 /** Return the root node of the linked-list tree generated by driving
- * the editor created by svn_repos_node_editor() with
- * svn_repos_dir_delta2(), which is stored in @a edit_baton.  This is
- * only really useful if used *after* the editor drive is completed.
+ * the editor created by svn_repos_node_editor(), which is stored in @a
+ * edit_baton.  This is only really useful if used *after* the editor
+ * drive is completed.
  */
 svn_repos_node_t *
 svn_repos_node_from_baton(void *edit_baton);


[prev in list] [next in list] [prev in thread] [next in thread]