[meld] diffutil: Add a few docstrings

[Kai Willadsen <kaiw src gnome org>]

commit 4de422904fa48364e527d7fc63af6d93813110cf
Author: Kai Willadsen <kai willadsen gmail com>
Date:   Sun Jul 10 10:25:18 2016 +1000

    diffutil: Add a few docstrings

 meld/diffutil.py |   16 +++++++++++++++-
 1 files changed, 15 insertions(+), 1 deletions(-)
---
diff --git a/meld/diffutil.py b/meld/diffutil.py
index 193531c..50f436c 100644
--- a/meld/diffutil.py
+++ b/meld/diffutil.py
@@ -133,6 +133,12 @@ class Differ(GObject.GObject):
         self.emit("diffs-changed", chunk_changes)
 
     def _update_line_cache(self):
+        """Cache a mapping from line index to per-pane chunk indices
+
+        This cache exists so that the UI can quickly query for current,
+        next and previous chunks when the current cursor line changes,
+        enabling better action sensitivity feedback.
+        """
         for i, l in enumerate(self.seqlength):
             # seqlength + 1 for after-last-line requests, which we do
             self._line_cache[i] = [(None, None, None)] * (l + 1)
@@ -256,6 +262,7 @@ class Differ(GObject.GObject):
             return chunk
 
     def get_chunk_starts(self, index):
+        """Return the starting lines of all chunks at an index"""
         chunks = self._merge_cache[index]
         chunk_starts = [
             chunks[0].start_b if chunks[0] else None,
@@ -265,7 +272,14 @@ class Differ(GObject.GObject):
         return chunk_starts
 
     def locate_chunk(self, pane, line):
-        """Find the index of the chunk which contains line."""
+        """Find the index of the chunk which contains line
+
+        Returns a tuple containing the current, previous and next chunk
+        indices in that order. If the line has no associated chunk,
+        None will be returned as the first element. If there are no
+        previous/next chunks then None will be returned as the
+        second/third elements.
+        """
         try:
             return self._line_cache[pane][line]
         except IndexError: