# HG changeset patch
# User Steve Losh <steve@stevelosh.com>
# Date 1255146111 14400
# Node ID dd45f9a0b74bc43ef0ed46bfc89aa0283dbe310a
# Parent  69bbcf7f0830914077fd811f5db2c395f8aa811b
Add more API documentation.

diff -r 69bbcf7f0830 -r dd45f9a0b74b review/api.py
--- a/review/api.py	Fri Oct 09 23:20:44 2009 -0400
+++ b/review/api.py	Fri Oct 09 23:41:51 2009 -0400
@@ -168,7 +168,28 @@
     
 
 class ReviewChangeset(object):
-    """The review data about one changeset in the target repository."""
+    """The review data about one changeset in the target repository.
+    
+    Individual changesets can be retrieved from a ReviewDatastore.
+    
+    Each ReviewChangeset stores a list of ReviewComment objects and a list
+    of ReviewSignoff objects:
+    
+        rcset = rd['tip']
+        rcset.comments
+        rcset.signoffs
+    
+    Comments and signoffs should be added to a changeset by using the
+    add_comment and add_signoff methods:
+    
+        rcset = rd['tip']
+        rcset.add_comment(...)
+        rcset.add_signoff(...)
+    
+    Diffs for files modified in a changeset can be retrived with the diffs
+    and full_diffs methods.  See the docs of those methods for more info.
+    
+    """
     def __init__(self, ui, repo, target, node):
         """Initialize a ReviewChangeset.
         
@@ -407,7 +428,24 @@
     
 
 class ReviewComment(_ReviewObject):
-    """A single review comment."""
+    """A single review comment.
+    
+    A list of comments can be retrieved from a ReviewChangeset.
+    
+    The following pieces of information are stored for comments:
+    
+        comment = rcset.comments[0]
+        comment.author
+        comment.datetime
+        comment.node
+        comment.filename
+        comment.lines
+        comment.message
+    
+    Each item is a string, except for datetime (a Python datetime.datetime
+    object) and lines (a list of ints).
+    
+    """
     def __init__(self, author, datetime, node, filename, lines, message, **extra):
         """Initialize a ReviewComment.
         
@@ -457,7 +495,22 @@
     
 
 class ReviewSignoff(_ReviewObject):
-    """A single review signoff."""
+    """A single review signoff.
+    
+    A list of signoffs can be retrieved from a ReviewChangeset.
+    
+    The following pieces of information are stored for signoffs:
+    
+        signoff = rcset.comments[0]
+        signoff.author
+        signoff.datetime
+        signoff.node
+        signoff.opinion
+        signoff.message
+    
+    Each item is a string.
+    
+    """
     def __init__(self, author, datetime, node, opinion, message, **extra):
         """Initialize a ReviewSignoff.