Re: [PATCH] Correct documentation for svn_repos_node_editor and friends

On Sat, Dec 18, 2010 at 20:43, Daniel Shahaf <d.s_at_daniel.shahaf.name> wrote:
> Erik Johansson wrote on Tue, Dec 14, 2010 at 19:19:17 +0100:
>> [[[
>> 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."
>>
>> One place where svn_repos_replay replaced svn_repos_dir_delta was in
>> combination with svn_repos_node_editor (only used in svnlook). This commit
>> updates the documentation for svn_repos_node_editor and friends to reflect
>> this.
>>
>> * subversion/include/svn_repos.h
>>   (svn_repos_node_editor, svn_repos_node_from_baton): Doc update
>> ]]]
>
> The patch basically does s/svn_repos_dir_delta2/svn_repos_replay2/g.
> However, despite the log message, I still don't understand why that is
> a correct change.

According to the log message for r846201 it seems like
svn_repos_replay is faster than svn_repos_dir_delta for some
operations. I can only assume that this is one such case.

> Why are we mentioning a specific driver at all?  Can svn_repos_node_editor()
> be driven only by svn_repos_replay2()?
>
> (I don't see why that would be the case.)  If not, then its doc string
> should avoid mention that the returned editor can be driven only by %s,
> when in fact it can be driven by anything.

I don't know the anything about the other drivers, but my assumption
is that any driver works, but svn_repos_replay is the prefered one in
this case.

> We have three mechanisms: svn_repos_dir_delta2(), svn_repos_begin_report2(),
> and svn_repos_replay2().  I think it would be useful to just mention all of
> them --- after all, none of them is deprecated and all of them can represent
> a tree delta using an editor.

Mention all on equal footing or say that svn_repos_replay2 is the preferred one?

I can fix the docs, but I don't know enough about svn api to actually
determine the correct fix. E.g. do all the drivers call methods in the
editor in the same order?

// Erik

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