Added: documentation for Tree.diff_*-Methods

docs/diff.rst

@@ -4,25 +4,34 @@ Diff
 
 A diff shows the changes between trees, an index or the working dir::
 
-    >>> head = repo.revparse_single('HEAD')
+    # Changes in the working tree not yet staged for the next commit
+    >>> repo.diff()
 
-    # Diff two trees
-    >>> t0 = head.tree
-    >>> t1 = head.parents[0].tree
-    >>> diff = t1.diff(t0)
+    # Changes between the index and your last commit
+    >>> self.diff(cached=True)
 
-    # Diff a tree with the index
-    >>> diff = head.tree.diff(repo.index)
+    # Changes in the working tree since your last commit
+    >>> self.diff('HEAD')
 
-    # Diff a tree with the current working dir
-    >>> diff = head.tree.diff()
+    # Changes between commits
+    >>> t0 = revparse_single('HEAD')
+    >>> t1 = revparse_single('HEAD^')
+    >>> repo.diff(t0, t1)
+    >>> t0.diff(t1)           # equivalent
+    >>> repo.diff('HEAD', 'HEAD^') # equivalent
 
     # Get all patches for a diff
-    >>> t0 = repo.revparse_single('HEAD^').tree
-    >>> t1 = repo.revparse_single('HEAD~3').tree
-    >>> diff = t0.diff(t1)
+    >>> diff = repo.diff('HEAD^', 'HEAD~3')
     >>> patches = [p for p in diff]
 
+    # Diffing the empty tree
+    >>> tree = revparse_single('HEAD').tree
+    >>> tree.diff_to_tree()
+
+    # Diff empty tree to a tree
+    >>> tree = revparse_single('HEAD').tree
+    >>> tree.diff_to_tree(swap=True)
+
 
 The Diff type
 ====================

src/tree.c

@@ -271,7 +271,10 @@ Tree_getitem(Tree *self, PyObject *value)
 }
 
 
-PyDoc_STRVAR(Tree_diff_to_workdir__doc__, "\n");
+PyDoc_STRVAR(Tree_diff_to_workdir__doc__,
+  "diff_to_workdir([flags]) -> Diff\n"
+  "\n"
+  "Show the changes between the tree and the workdir.\n");
 
 PyObject *
 Tree_diff_to_workdir(Tree *self, PyObject *args)
@@ -297,7 +300,10 @@ Tree_diff_to_workdir(Tree *self, PyObject *args)
 }
 
 
-PyDoc_STRVAR(Tree_diff_to_index__doc__, "\n");
+PyDoc_STRVAR(Tree_diff_to_index__doc__,
+  "diff_to_index(index, [flags]) -> Diff\n"
+  "\n"
+  "Show the changes between the index and a given tree.\n");
 
 PyObject *
 Tree_diff_to_index(Tree *self, PyObject *args, PyObject *kwds)
@@ -324,7 +330,11 @@ Tree_diff_to_index(Tree *self, PyObject *args, PyObject *kwds)
 }
 
 
-PyDoc_STRVAR(Tree_diff_to_tree__doc__, "\n");
+PyDoc_STRVAR(Tree_diff_to_tree__doc__,
+  "diff_to_tree([tree, flags, swap]) -> Diff\n"
+  "\n"
+  "Show the changes between two trees. If no tree is given the empty tree will"
+  "be used instead.\n");
 
 PyObject *
 Tree_diff_to_tree(Tree *self, PyObject *args, PyObject *kwds)