Split the api docs into separate pages.

The :meth: references are annoying, and some aren't right yet. :(

2 files changed, 34 insertions, 30 deletions

diff --git a/coverage/control.py b/coverage/control.py
index 4837356d..ad3c1bdf 100644
--- a/coverage/control.py
+++ b/coverage/control.py
@@ -191,8 +191,8 @@ class Coverage(object):
         """Set all the initial state.
 
         This is called by the public methods to initialize state. This lets us
-        construct a Coverage object, then tweak its state before this function
-        is called.
+        construct a :class:`Coverage` object, then tweak its state before this
+        function is called.
 
         """
         if self._inited:
@@ -611,11 +611,12 @@ class Coverage(object):
     def start(self):
         """Start measuring code coverage.
 
-        Coverage measurement actually occurs in functions called after `start`
-        is invoked.  Statements in the same scope as `start` won't be measured.
+        Coverage measurement actually occurs in functions called after
+        :meth:`.start` is invoked.  Statements in the same scope as
+        :meth:`.start` won't be measured.
 
-        Once you invoke `start`, you must also call `stop` eventually, or your
-        process might not shut down cleanly.
+        Once you invoke :meth:`.start`, you must also call :meth:`.stop`
+        eventually, or your process might not shut down cleanly.
 
         """
         self._init()
@@ -695,8 +696,8 @@ class Coverage(object):
     def get_exclude_list(self, which='exclude'):
         """Return a list of excluded regex patterns.
 
-        `which` indicates which list is desired.  See `exclude` for the lists
-        that are available, and their meaning.
+        `which` indicates which list is desired.  See :meth:`.exclude` for the
+        lists that are available, and their meaning.
 
         """
         self._init()
@@ -739,7 +740,7 @@ class Coverage(object):
 
         Also warn about various problems collecting data.
 
-        Returns a :class:`CoverageData`, the collected coverage data.
+        Returns a :class:`coverage.CoverageData`, the collected coverage data.
 
         """
         self._init()
@@ -927,7 +928,7 @@ class Coverage(object):
         marker to indicate the coverage of the line.  Covered lines have ">",
         excluded lines have "-", and missing lines have "!".
 
-        See `coverage.report()` for other arguments.
+        See :meth:`.report` for other arguments.
 
         """
         self.get_data()
@@ -951,7 +952,7 @@ class Coverage(object):
         `title` is a text string (not HTML) to use as the title of the HTML
         report.
 
-        See `coverage.report()` for other arguments.
+        See :meth:`.report` for other arguments.
 
         Returns a float, the total percentage covered.
 
@@ -975,7 +976,7 @@ class Coverage(object):
         Each module in `morfs` is included in the report.  `outfile` is the
         path to write the file to, "-" will write to stdout.
 
-        See `coverage.report()` for other arguments.
+        See :meth:`.report` for other arguments.
 
         Returns a float, the total percentage covered.
 
diff --git a/coverage/data.py b/coverage/data.py
index 0fa2c878..56233e5e 100644
--- a/coverage/data.py
+++ b/coverage/data.py
@@ -22,13 +22,15 @@ class CoverageData(object):
 
     This class is the public supported API to the data coverage.py collects
     during program execution.  It includes information about what code was
+    executed. It does not include information from the analysis phase, to
+    determine what lines could have been executed, or what lines were not
     executed.
 
     .. note::
 
         The file format is not documented or guaranteed.  It will change in
-        the future, in possibly complicated ways.  Use this API to avoid
-        disruption.
+        the future, in possibly complicated ways.  Do not read coverage.py
+        data files directly.  Use this API to avoid disruption.
 
     There are a number of kinds of data that can be collected:
 
@@ -46,32 +48,33 @@ class CoverageData(object):
       written during "coverage run", and then accumulated during "coverage
       combine".
 
-    To read a coverage.py data file, use :meth:`read_file`, or :meth:`read` if
-    you have an already-opened file.  You can then access the line, arc, or
-    file tracer data with :meth:`lines`, :meth:`arcs`, or :meth:`file_tracer`.
-    Run information is available with :meth:`run_infos`.
+    To read a coverage.py data file, use :meth:`.read_file`, or :meth:`.read`
+    if you have an already-opened file.  You can then access the line, arc, or
+    file tracer data with :meth:`.lines`, :meth:`.arcs`, or
+    :meth:`.file_tracer`.  Run information is available with
+    :meth:`.run_infos`.
 
-    The :meth:`has_arcs` method indicates whether arc data is available.  You
-    can get a list of the files in the data with :meth:`measured_files`.
-    A summary of the line data is available from :meth:`line_counts`.  As with
+    The :meth:`.has_arcs` method indicates whether arc data is available.  You
+    can get a list of the files in the data with :meth:`.measured_files`.
+    A summary of the line data is available from :meth:`.line_counts`.  As with
     most Python containers, you can determine if there is any data at all by
     using this object as a boolean value.
 
 
     Most data files will be created by coverage.py itself, but you can use
-    methods here to create data files if you like.  The :meth:`set_lines`,
-    :meth:`set_arcs`, and :meth:`set_file_tracers` methods add data, in ways
-    that are convenient for coverage.py.  The :meth:`add_run_info` method adds
+    methods here to create data files if you like.  The :meth:`.set_lines`,
+    :meth:`.set_arcs`, and :meth:`.set_file_tracers` methods add data, in ways
+    that are convenient for coverage.py.  The :meth:`.add_run_info` method adds
     key-value pairs to the run information.
 
-    To add a file without any measured data, use :meth:`touch_file`.
+    To add a file without any measured data, use :meth:`.touch_file`.
 
-    You write to a named file with :meth:`write_file`, or to an already opened
-    file with :meth:`write`.
+    You write to a named file with :meth:`.write_file`, or to an already opened
+    file with :meth:`.write`.
 
-    You can clear the data in memory with :meth:`erase`.  Two data collections
-    can be combined by using :meth:`update` on one `CoverageData`, passing it
-    the other.
+    You can clear the data in memory with :meth:`.erase`.  Two data collections
+    can be combined by using :meth:`.update` on one :class:`CoverageData`,
+    passing it the other.
 
     """