# HG changeset patch
# User Steve Losh <steve@stevelosh.com>
# Date 1278994966 14400
# Node ID 22f23f51ce593091b580a67c8b3e7eba7c44a4c2
# Parent  d3edf7c43e7ac80a361cf15e7b537d6f645f6d1a
docs/api: flesh out the api docs

diff -r d3edf7c43e7a -r 22f23f51ce59 docs/api.rst
--- a/docs/api.rst	Mon Jul 12 23:39:33 2010 -0400
+++ b/docs/api.rst	Tue Jul 13 00:22:46 2010 -0400
@@ -52,11 +52,144 @@
     |
     `-- other files ...
 
+All review data for a changeset is stored in::
+
+    .hg/review/{{ changeset hash }}/
+
+A ``.exists`` file is included in that directory when code review for
+that changeset is initialized. This allows us to check if a given changeset has
+been initialized for code review very quickly.
+
+Comments for a changeset are stored in::
+
+    .hg/review/{{ changeset hash }}/comments/{{ comment hash }}
+
+Signoffs for a changeset are stored in::
+
+    .hg/review/{{ changeset hash }}/signoffs/{{ signoff hash }}
+
 File Formats
 ------------
 
+hg-review's file format is (fairly) stable and is designed to be easily parsed
+to enable export to other code review systems.
+
+Comment and signoff files are stored as JSON. The files are indented four
+spaces per level to make them more human-readable.
+
+``.exists`` Files
+'''''''''''''''''
+
+The ``.exists`` file is always empty. It simply exists to make looking up
+whether a given changeset has been initialized faster. It may go away in the
+future -- do not depend on it.
+
+Comment Files
+'''''''''''''
+
+Here is a sample comment file::
+
+    {
+        "author": "Steve Losh <steve@stevelosh.com>", 
+        "file": [
+            "reykjavi\u0301k.txt", 
+            "cmV5YWphdmnMgWsudHh0"
+        ], 
+        "hgdate": "Mon Jul 12 23:55:51 2010 -0400", 
+        "lines": [
+            0
+        ], 
+        "message": "Sample.", 
+        "node": "0e987f91e9b6628b26a30c5d00668a15fae8f22f", 
+        "style": "markdown"
+    }
+
+Comment files have some or all of the following fields:
+
+``author``
+    The Mercurial username of the person that added this comment.
+
+``file``
+    A list of two strings. The first string is a (JSON-encoded) representation
+    of the UTF-8 filename. The second string is a base64 encoded version of the
+    actual bytes of the filename (which is what Mercurial gives and expects to
+    receive internally). If this is a review-level comment both strings will be
+    blank.
+
+``hgdate``
+    The date and time the comment was added (or last edited).
+
+``lines``
+    A list of integers representing the lines of the file that this comment
+    applies to. If this is a file-level or review-level comment the list will
+    be empty.
+
+``message``
+    A string representing the raw comment message.
+
+``node``
+    A string representing the hash of the changset this comment belongs to, for
+    easy lookup later.
+
+``style``
+    A string representing the style of this comment -- this will be
+    ``markdown`` for Markdown comments and blank for plain-text comments. More
+    styles may be added in the future.
+
+Signoff Files
+'''''''''''''
+
+Here is a sample signoff file::
+
+    {
+        "author": "Steve Losh <steve@stevelosh.com>", 
+        "hgdate": "Tue Jul 13 00:16:00 2010 -0400", 
+        "message": "Sample.", 
+        "node": "0e987f91e9b6628b26a30c5d00668a15fae8f22f", 
+        "opinion": "yes", 
+        "style": "markdown"
+    }
+
+Signoff files have some or all of the following fields:
+
+``author``
+    The Mercurial username of the person that added this comment.
+
+``hgdate``
+    The date and time the comment was added (or last edited).
+
+``message``
+    A string representing the raw comment message.
+
+``node``
+    A string representing the hash of the changset this comment belongs to, for
+    easy lookup later.
+
+``opinion``
+    A string representing the signoff opinion. This will be ``yes``, ``no``, or
+    a blank string (for a neutral signoff).
+
+``style``
+    A string representing the style of this comment -- this will be
+    ``markdown`` for Markdown comments and blank for plain-text comments. More
+    styles may be added in the future.
+
 Command Line Interface
 ----------------------
 
-Python API
-----------
+hg-review's command line interface is (fairly) stable. If you want to interact
+with review data for a repository this is the safest method to use.
+
+See the :doc:`command line interface documentation </cli>` for more details.
+
+Internal Python API
+-------------------
+
+hg-review's internal Python implementation is *not* stable. It may change at
+any time. Relying on it virtually guarantees your application will break at
+some point.
+
+For a more stable API you should use the command line interface.
+
+The Python API will be documented later, but is not a high priority at the
+moment because of its volatility.