From f4f68b6442e26a29a86cb7bcd3a3b2cfe01438d6 Mon Sep 17 00:00:00 2001
From: Ian Cordasco <graffatcolmingov@gmail.com>
Date: Sun, 31 Jan 2016 23:59:53 -0600
Subject: [PATCH] Document our plugin handling

---
 docs/source/index.rst                    |  1 +
 docs/source/internal/plugin_handling.rst | 73 ++++++++++++++++++++++++
 flake8/plugins/manager.py                |  2 +-
 3 files changed, 75 insertions(+), 1 deletion(-)
 create mode 100644 docs/source/internal/plugin_handling.rst

diff --git a/docs/source/index.rst b/docs/source/index.rst
index 0263664..4a50a5d 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -19,6 +19,7 @@ Plugin Developer Guide
     :maxdepth: 2
 
     internal/option_handling
+    internal/plugin_handling
 
 Developer Guide
 ---------------
diff --git a/docs/source/internal/plugin_handling.rst b/docs/source/internal/plugin_handling.rst
new file mode 100644
index 0000000..547b5ca
--- /dev/null
+++ b/docs/source/internal/plugin_handling.rst
@@ -0,0 +1,73 @@
+Plugin Handling
+===============
+
+Plugin Management
+-----------------
+
+Flake8 3.0 added support for two other plugins besides those which define new
+checks. It now supports:
+
+- extra checks
+
+- alternative report formatters
+
+- listeners to auto-correct violations of checks
+
+To facilitate this, Flake8 needed a more mature way of managing plugins. As
+such, we developed the |PluginManager| which accepts a namespace and will load
+the plugins for that namespace. A |PluginManager| creates and manages many
+|Plugin| instances.
+
+A |Plugin| lazily loads the underlying entry-point provided by setuptools.
+The entry-point will be loaded either by calling
+:meth:`~flake8.plugins.manager.Plugin.load_plugin` or accessing the ``plugin``
+attribute. We also use this abstraction to retrieve options that the plugin
+wishes to register and parse.
+
+The only public method that the |PluginManager| provides is
+:meth:`~flake8.plugins.manager.PluginManager.map`. This will accept a function
+(or other callable) and call it with each plugin as the first parameter.
+
+We build atop the |PluginManager| with the |PTM|. It is expected that users of
+the |PTM| will subclass it and specify the ``namespace``, e.g.,
+
+.. code-block:: python
+
+    class ExamplePluginType(flake8.plugin.manager.PluginTypeManager):
+        namespace = 'example-plugins'
+
+This provides a few extra methods via the |PluginManager|'s ``map`` method.
+
+Finally, we create three classes of plugins:
+
+- :class:`~flake8.plugins.manager.Checkers`
+
+- :class:`~flake8.plugins.manager.Listeners`
+
+- :class:`~flake8.plugins.manager.ReportFormatters`
+
+These are used to interact with each of the types of plugins individually.
+
+API Documentation
+-----------------
+
+.. autoclass:: flake8.plugins.manager.PluginManager
+    :members:
+    :special-members: __init__, __contains__, __getitem__
+
+.. autoclass:: flake8.plugins.manager.Plugin
+    :members:
+    :special-members: __init__
+
+.. autoclass:: flake8.plugins.manager.PluginTypeManager
+    :members:
+
+.. autoclass:: flake8.plugins.manager.Checkers
+
+.. autoclass:: flake8.plugins.manager.Listeners
+
+.. autoclass:: flake8.plugins.manager.ReportFormatters
+
+.. |PluginManager| replace:: :class:`~flake8.plugins.manager.PluginManager`
+.. |Plugin| replace:: :class:`~flake8.plugins.manager.Plugin`
+.. |PTM| replace:: :class:`~flake8.plugins.manager.PluginTypeManager`
diff --git a/flake8/plugins/manager.py b/flake8/plugins/manager.py
index f73d006..570c1d0 100644
--- a/flake8/plugins/manager.py
+++ b/flake8/plugins/manager.py
@@ -171,7 +171,7 @@ class PluginManager(object):
             LOG.info('Loaded %r for plugin "%s".', self.plugins[name], name)
 
     def map(self, func, *args, **kwargs):
-        """Call ``func`` with the plugin and *args and **kwargs after.
+        r"""Call ``func`` with the plugin and \*args and \**kwargs after.
 
         This yields the return value from ``func`` for each plugin.