Mailing-List: contact dev-help@subversion.apache.org; run by ezmlm
Precedence: bulk
Date: Mon, 3 Jan 2011 03:22:04 +0200
From: Daniel Shahaf <danielsh@apache.org>
To: Erik Johansson <erik@ejohansson.se>
Cc: dev@subversion.apache.org
Subject: Re: [PATCH] Correct documentation for svn_repos_node_editor and
	friends
Message-ID: <20110103012204.GA14065@daniel3.local>
References: <AANLkTik9gF8S4FgN4y47=hgMpFL8Cg8AEx=TFNWDcGJX@mail.gmail.com>
 <AANLkTimPcE6H16HnbAxb7kRCxJXO_3NZ-FSrUdzLwtpw@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <AANLkTimPcE6H16HnbAxb7kRCxJXO_3NZ-FSrUdzLwtpw@mail.gmail.com>
User-Agent: Mutt/1.5.18 (2008-05-17)

Erik,

Thanks for the patch; I committed it with minor changes in r1054513.

Daniel


Erik Johansson wrote on Wed, Dec 29, 2010 at 12:00:37 +0100:
> 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

> 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);