[MERGE] Refactor diffing

[Robert Collins]

On Thu, 2007-11-22 at 14:45 -0500, Aaron Bentley wrote:

A few comments

Differ seems strange to me. We don't have e.g. TreeTransformer for
example. I think it would be a bit easier to understand with a noun as
the class name, and more consistent with our other code.

The tests look good.

I think FileDiffer should be PathDiff, because the interface handles
diffing anything in a tree - file or directory. Or perhaps EntryDiff, or
something less likely to be confused with 'regular files'.


+class TreeDiffer(object):
+    """Object for comparing the contents of two trees"""

How about this as a docstring (using your class names, see above for my
rename preference).
    """Provides textual representations of the difference between two
trees.

    A TreeDiffer examines two tree and where a fileid has altered
    between them generates a textual representation of the difference.
    TreeDiffer uses a sequence of PathDiff objects which are each 
    given the opportunity to handle a given altered fileid. The list
    of PathDiff objects can be extended globally by appending to 
    TreeDiffer._diff_factories, or for a specific diff operation by
    supplying the extra_differ option to the appropriate method.
    """

Basically a bit of prose to make it obvious to folk encountering this
class what it's all about, hopefully without lots of duplication
(because its about intent and structure).

It might also be nice to reference TreeDiffer and FileDiffer as key
things to look at in the module docstring.

Martin may chime in here and say 'what about the developers guide'. I
think though that this stuff is really quite specific to this module,
and as long as the developers guide says 'text representations of diffs
are done by bzrlib.diff' then the loop is closed for finding out about
this stuff (without having to bootstrap all the way from 'bzr' ->
'bzr.commands' etc.)

-Rob

-- 
GPG key available at: <http://www.robertcollins.net/keys.txt>.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20071123/4785b3ad/attachment-0001.pgp