# HG changeset patch
# User Steve Losh <steve@stevelosh.com>
# Date 1255143191 14400
# Node ID d32fa8336dc2ff4d42293b3a05e4438975697b51
# Parent  554175d9a71cabfc8426192f2a47734fdb685beb
Add a docstring for the new diffs() method.

diff -r 554175d9a71c -r d32fa8336dc2 review/api.py
--- a/review/api.py	Fri Oct 09 19:33:55 2009 -0400
+++ b/review/api.py	Fri Oct 09 22:53:11 2009 -0400
@@ -313,6 +313,40 @@
         return diffs
     
     def diffs(self, filenames=None, context=5):
+        """Return a mapping of diff lines for the given files (or all).
+        
+        If the filenames argument is not used, diffs for every file in the
+        changeset will be returned.
+        
+        The diffs are returned in a dictionary of the form:
+        
+        { 
+            'filename': {
+                # the line number of the last line of the FULL diff
+                'max': 90,
+                
+                # A sorted list of tuples of (line_number, line_content)
+                'content': [
+                    (10, ' context line'),
+                    (11, ' context line'),
+                    (12, '-removed line'),
+                    (13, '+added line'),
+                    (14, ' context line'),
+                    (15, ' context line'),
+                    (39, ' context line'),
+                    (40, ' context line'),
+                    (41, '-removed line'),
+                    (42, '+added line'),
+                    (43, ' context line'),
+                    (44, ' context line'),
+                ],
+            },
+        }
+        
+        There's a lot of structure there, but it will provide everything you
+        need to display contextualized diffs.
+        
+        """
         ds = self.full_diffs(filenames, {})
         
         def _filter_diff(d):