# HG changeset patch
# User Steve Losh <steve@stevelosh.com>
# Date 1255039686 14400
# Node ID 022175cc8a90a63c3150b2b9a0dd754ed32727ad
# Parent  cc9456bb289bb9e2e41463ee08692861217c6f9b
Add more API documentation (notice a trend yet?).

diff -r cc9456bb289b -r 022175cc8a90 review/api.py
--- a/review/api.py	Thu Oct 08 17:58:57 2009 -0400
+++ b/review/api.py	Thu Oct 08 18:08:06 2009 -0400
@@ -155,7 +155,7 @@
 class ReviewChangeset(object):
     """The review data about one changeset in the target repository."""
     def __init__(self, ui, repo, target, node):
-        """A changeset being reviewed.
+        """Initialize a ReviewChangeset.
         
         You shouldn't need to create these directly -- use a ReviewDatastore
         object to get them:
@@ -341,6 +341,17 @@
 class ReviewComment(_ReviewObject):
     """A single review comment."""
     def __init__(self, author, datetime, node, filename, lines, message, **extra):
+        """Initialize a ReviewComment.
+        
+        You shouldn't need to create these directly -- use a ReviewChangeset
+        to add comments and retrieve existing ones:
+        
+            review_data = ReviewDatastore(ui, repo)
+            tip_review = review_data['tip']
+            tip_review.add_comment(...)
+            tip_comments = tip_review.comments
+        
+        """
         super(ReviewComment, self).__init__(
             container='comments', commit_message=messages.COMMIT_COMMENT,
         )
@@ -352,12 +363,20 @@
         self.message = message
     
     def render_data(self):
+        """Render the data of this comment into a string for writing to disk.
+        
+        You probably don't need to call this directly, the add_signoff method
+        of a ReviewChangeset will handle it for you.
+        
+        """
         datetime = str(self.datetime)
         lines = ','.join(self.lines)
         return templates.COMMENT_FILE_TEMPLATE % ( self.author, datetime,
             self.node, self.filename, lines, self.message )
     
     def __str__(self):
+        """Stringify this comment for easy printing (for debugging)."""
+        
         return '\n'.join(map(str, [
             self.author,
             self.datetime,
@@ -372,6 +391,17 @@
 class ReviewSignoff(_ReviewObject):
     """A single review signoff."""
     def __init__(self, author, datetime, node, opinion, message, **extra):
+        """Initialize a ReviewSignoff.
+        
+        You shouldn't need to create these directly -- use a ReviewChangeset
+        to add signoffs and retrieve existing ones:
+        
+            review_data = ReviewDatastore(ui, repo)
+            tip_review = review_data['tip']
+            tip_review.add_signoff(...)
+            tip_signoffs = tip_review.signoffs
+        
+        """
         super(ReviewSignoff, self).__init__(
             container='signoffs', commit_message=messages.COMMIT_SIGNOFF,
             delete_message=messages.DELETE_SIGNOFF,
@@ -383,6 +413,12 @@
         self.message = message
     
     def render_data(self):
+        """Render the data of this signoff into a string for writing to disk.
+        
+        You probably don't need to call this directly, the add_signoff method
+        of a ReviewChangeset will handle it for you.
+        
+        """
         datetime = str(self.datetime)
         return templates.SIGNOFF_FILE_TEMPLATE % ( self.author, datetime,
             self.node, self.opinion, self.message )