# HG changeset patch
# User Steve Losh <steve@stevelosh.com>
# Date 1255038774 14400
# Node ID 8cea29aa955f400f34e10e5b390d9735271ff0ba
# Parent  62c8ba974c19949bee9babe580cde6bbe60f8853
Add more documentation to the API.

diff -r 62c8ba974c19 -r 8cea29aa955f review/api.py
--- a/review/api.py	Thu Oct 08 17:52:45 2009 -0400
+++ b/review/api.py	Thu Oct 08 17:52:54 2009 -0400
@@ -193,7 +193,14 @@
                   'addremove': True, })
     
     def add_signoff(self, message, opinion='', force=False):
-        """Add (and commit) a signoff for the given revision."""
+        """Add (and commit) a signoff for the given revision.
+        
+        The opinion argument should be 'yes', 'no', or ''.
+        
+        If a signoff from the user already exists, a SignoffExists exception
+        will be raised unless the force argument is used.
+        
+        """
         existing = filter(lambda s: s.author == self.ui.username(), self.signoffs)
         
         if existing:
@@ -206,7 +213,19 @@
         signoff.commit(self.ui, self.repo)
     
     def add_comment(self, message, filename='', lines=[]):
-        """Add (and commit) a comment for the given file and lines."""
+        """Add (and commit) a comment for the given file and lines.
+        
+        The filename should be normalized to the format Mercurial expects,
+        that is: relative to the root of the repository and using forward
+        slashes as the separator.  Paths can be converted with the
+        sanitize_path function in this module.
+        
+        If the comment is on one or more lines, a filename *must* be given.
+        
+        Line numbers should be passed as a list, even if there is only one.
+        See the full_diffs function for how to refer to line numbers.
+        
+        """
         if filename and filename not in self.target[self.node].files():
             raise FileNotInChangeset(filename)
         
@@ -215,7 +234,33 @@
         comment.commit(self.ui, self.repo)
     
     def full_diffs(self, filenames=None, opts={}):
-        """Return diffs of the given files."""
+        """Return full diffs of the given files (or all files).
+        
+        If the filenames argument is not used, diffs for every file in the
+        changeset will be returned.
+        
+        The diffs are returned as a dictionary in the form:
+        
+            { 'filename': 'string of the diff' }
+        
+        All headers are stripped, so the an entire diff looks like this:
+        
+             unchanged line
+             unchanged line
+            -removed line
+            -removed line
+            +added line
+             unchanged line
+            -removed line
+            -removed line
+             unchanged line
+             unchanged line
+        
+        When adding a comment, the line number given should be the line
+        number from this diff (starting at 0).  To comment on the first two
+        removed lines in the above example you would pass [2, 3].
+        
+        """
         
         target_files = self.target[self.node].files()
         if not filenames: