Separate the plugin API docs from the 'using plugins' docs.

1 files changed, 9 insertions, 1 deletions

diff --git a/coverage/plugin.py b/coverage/plugin.py
index ac407047..2f28777a 100644
--- a/coverage/plugin.py
+++ b/coverage/plugin.py
@@ -82,7 +82,9 @@ class CoveragePlugin(object):
         """Get the :class:`FileReporter` class to use for a file.
 
         This will only be invoked if `filename` returns non-None from
-        :meth:`file_tracer`.  It's an error to return None.
+        :meth:`file_tracer`.  It's an error to return None from this method.
+
+        Returns a :class:`FileReporter` object to use to report on `filename`.
 
         """
         _needs_to_implement(self, "file_reporter")
@@ -106,6 +108,9 @@ class FileTracer(object):
     way you like.  A natural choice would be to pass the file name given to
     `file_tracer`.
 
+    `FileTracer` objects should only be created in the
+    :meth:`CoveragePlugin.file_tracer` method.
+
     See :ref:`howitworks` for details of the different coverage.py phases.
 
     """
@@ -181,6 +186,9 @@ class FileReporter(object):
 
     See :ref:`howitworks` for details of the different coverage.py phases.
 
+    `FileReporter` objects should only be created in the
+    :meth:`CoveragePlugin.file_reporter` method.
+
     There are many methods here, but only :meth:`lines` is required, to provide
     the set of executable lines in the file.