From 83dd81a44526eab408ffc466e355263e76c8b2e0 Mon Sep 17 00:00:00 2001
From: Ian Cordasco <graffatcolmingov@gmail.com>
Date: Tue, 19 Jan 2016 07:45:25 -0600
Subject: [PATCH] Add missing docstrings to plugin submodule

---
 flake8/options/manager.py  |  1 +
 flake8/plugins/__init__.py |  1 +
 flake8/plugins/manager.py  | 16 ++++++++++++++++
 flake8/plugins/pyflakes.py |  6 ++++++
 4 files changed, 24 insertions(+)

diff --git a/flake8/options/manager.py b/flake8/options/manager.py
index 46e9f86..1dd6c8d 100644
--- a/flake8/options/manager.py
+++ b/flake8/options/manager.py
@@ -159,6 +159,7 @@ class OptionManager(object):
 
     @staticmethod
     def format_plugin(plugin_tuple):
+        """Convert a plugin tuple into a dictionary mapping name to value."""
         return dict(zip(["entry", "name", "version"], plugin_tuple))
 
     def add_option(self, *args, **kwargs):
diff --git a/flake8/plugins/__init__.py b/flake8/plugins/__init__.py
index e69de29..fda6a44 100644
--- a/flake8/plugins/__init__.py
+++ b/flake8/plugins/__init__.py
@@ -0,0 +1 @@
+"""Submodule of built-in plugins and plugin managers."""
diff --git a/flake8/plugins/manager.py b/flake8/plugins/manager.py
index 1afdaa9..e4ad20e 100644
--- a/flake8/plugins/manager.py
+++ b/flake8/plugins/manager.py
@@ -6,6 +6,14 @@ import pkg_resources
 
 LOG = logging.getLogger(__name__)
 
+__all__ = (
+    'Checkers',
+    'Listeners',
+    'Plugin',
+    'PluginManager',
+    'ReportFormatters',
+)
+
 
 class Plugin(object):
     """Wrap an EntryPoint from setuptools and other logic."""
@@ -25,17 +33,23 @@ class Plugin(object):
         self._plugin = None
 
     def __repr__(self):
+        """Provide an easy to read description of the current plugin."""
         return 'Plugin(name="{0}", entry_point="{1}")'.format(
             self.name, self.entry_point
         )
 
     @property
     def plugin(self):
+        """The loaded (and cached) plugin associated with the entry-point.
+
+        This property implicitly loads the plugin and then caches it.
+        """
         self.load_plugin()
         return self._plugin
 
     @property
     def version(self):
+        """Return the version attribute on the plugin."""
         return self.plugin.version
 
     def execute(self, *args, **kwargs):
@@ -124,10 +138,12 @@ class PluginManager(object):
         self._load_all_plugins()
 
     def __contains__(self, name):
+        """Check if the entry-point name is in this plugin manager."""
         LOG.debug('Checking for "%s" in plugin manager.', name)
         return name in self.plugins
 
     def __getitem__(self, name):
+        """Retrieve a plugin by its entry-point name."""
         LOG.debug('Retrieving plugin for "%s".', name)
         return self.plugins[name]
 
diff --git a/flake8/plugins/pyflakes.py b/flake8/plugins/pyflakes.py
index c801e54..85465fc 100644
--- a/flake8/plugins/pyflakes.py
+++ b/flake8/plugins/pyflakes.py
@@ -1,3 +1,4 @@
+"""Plugin built-in to Flake8 to treat pyflakes as a plugin."""
 # -*- coding: utf-8 -*-
 from __future__ import absolute_import
 try:
@@ -40,10 +41,12 @@ patch_pyflakes()
 
 class FlakesChecker(pyflakes.checker.Checker):
     """Subclass the Pyflakes checker to conform with the flake8 API."""
+
     name = 'pyflakes'
     version = pyflakes.__version__
 
     def __init__(self, tree, filename):
+        """Initialize the PyFlakes plugin with an AST tree and filename."""
         filename = utils.normalize_paths(filename)[0]
         withDoctest = self.withDoctest
         included_by = [include for include in self.include_in_doctest
@@ -65,6 +68,7 @@ class FlakesChecker(pyflakes.checker.Checker):
 
     @classmethod
     def add_options(cls, parser):
+        """Register options for PyFlakes on the Flake8 OptionManager."""
         parser.add_option(
             '--builtins', parse_from_config=True, comma_separated_list=True,
             help="define more built-ins, comma separated",
@@ -91,6 +95,7 @@ class FlakesChecker(pyflakes.checker.Checker):
 
     @classmethod
     def parse_options(cls, options):
+        """Parse option values from Flake8's OptionManager."""
         if options.builtins:
             cls.builtIns = cls.builtIns.union(options.builtins.split(','))
         cls.withDoctest = options.doctests
@@ -125,6 +130,7 @@ class FlakesChecker(pyflakes.checker.Checker):
                              'both for doctesting.' % inc_exc)
 
     def run(self):
+        """Run the plugin."""
         for m in self.messages:
             col = getattr(m, 'col', 0)
             yield m.lineno, col, (m.flake8_msg % m.message_args), m.__class__