More plugin docscoverage-4.0b1

3 files changed, 18 insertions, 8 deletions

diff --git a/coverage/__init__.py b/coverage/__init__.py
index f9e8a04..88b6c2f 100644
--- a/coverage/__init__.py
+++ b/coverage/__init__.py
@@ -13,7 +13,7 @@ from coverage.version import __version__, __url__
 from coverage.control import Coverage, process_startup
 from coverage.data import CoverageData
 from coverage.misc import CoverageException
-from coverage.plugin import CoveragePlugin
+from coverage.plugin import CoveragePlugin, FileTracer, FileReporter
 
 # Backward compatibility.
 coverage = Coverage
diff --git a/coverage/plugin.py b/coverage/plugin.py
index 5b0479c..f4182b0 100644
--- a/coverage/plugin.py
+++ b/coverage/plugin.py
@@ -10,15 +10,12 @@ from coverage import files
 from coverage.misc import _needs_to_implement
 
 
-# TODO: document that the plugin objects may be decorated with attributes with
-# named "_coverage_*".
-
 class CoveragePlugin(object):
     """Base class for coverage.py plugins.
 
-    To write a coverage.py plugin, create a subclass of `CoveragePlugin`.
-    You can override methods here to participate in various aspects of
-    coverage.py's processing.
+    To write a coverage.py plugin, create a module with a subclass of
+    :class:`CoveragePlugin`.  You can override methods in your class to
+    participate in various aspects of coverage.py's processing.
 
     Currently the only plugin type is a file tracer, for implementing
     measurement support for non-Python files.  File tracer plugins implement
@@ -28,6 +25,19 @@ class CoveragePlugin(object):
     Any plugin can optionally implement :meth:`sys_info` to provide debugging
     information about their operation.
 
+    Coverage.py will store its own information on your plugin, with attributes
+    starting with "_coverage_".  Don't be startled.
+
+    To register your plugin, define a function called `coverage_init` in your
+    module::
+
+        def coverage_init(reg, options):
+            reg.add_file_tracer(MyPlugin())
+
+    The `reg.add_file_tracer` method takes an instance of your plugin.  If your
+    plugin takes options, the `options` argument is a dictionary of your
+    plugin's options from the .coveragerc file.
+
     """
 
     def file_tracer(self, filename):        # pylint: disable=unused-argument
diff --git a/doc/plugins.rst b/doc/plugins.rst
index b8cb1f1..c0466b2 100644
--- a/doc/plugins.rst
+++ b/doc/plugins.rst
@@ -53,7 +53,7 @@ coverage.py plugin called ``something.plugin``.
 Plugin API
 ----------
 
-.. module:: coverage.plugin
+.. module:: coverage
 
 .. autoclass:: CoveragePlugin
     :members: