From 72833b629a506923f4df01cc114032c9343f8e4a Mon Sep 17 00:00:00 2001
From: Ian Cordasco <graffatcolmingov@gmail.com>
Date: Mon, 16 May 2016 20:15:14 -0500
Subject: [PATCH] Start adding documentation about developing plugins

---
 docs/source/dev/plugin_parameters.rst | 48 +++++++++++++++++++++++++++
 docs/source/index.rst                 |  1 +
 flake8/processor.py                   |  1 +
 3 files changed, 50 insertions(+)
 create mode 100644 docs/source/dev/plugin_parameters.rst

diff --git a/docs/source/dev/plugin_parameters.rst b/docs/source/dev/plugin_parameters.rst
new file mode 100644
index 0000000..a2c8c7f
--- /dev/null
+++ b/docs/source/dev/plugin_parameters.rst
@@ -0,0 +1,48 @@
+====================================
+ Receiving Information For A Plugin
+====================================
+
+Plugins to Flake8 have a great deal of information that they can request from
+a :class:`~flake8.processor.FileProcessor` instance. Historically, Flake8 has
+supported two types of plugins:
+
+#. classes that accept parsed abstract syntax trees (ASTs)
+
+#. functions that accept a range of arguments
+
+Flake8 now does not distinguish between the two types of plugins. Any plugin
+can accept either an AST or a range of arguments. Further, any plugin that has
+certain callable attributes can also register options and receive parsed
+options.
+
+Indicating Desired Data
+=======================
+
+Flake8 inspects the plugin's signature to determine what parameters it expects
+using :func:`flake8.utils.parameters_for`.
+:attr:`flake8.plugins.manager.Plugin.parameters` caches the values so that
+each plugin makes that fairly expensive call once per plugin. When processing 
+a file, a plugin can ask for any of the following:
+
+- :attr:`~flake8.processor.FileProcessor.blank_before`
+- :attr:`~flake8.processor.FileProcessor.blank_lines`
+- :attr:`~flake8.processor.FileProcessor.checker_state`
+- :attr:`~flake8.processor.FileProcessor.indect_char`
+- :attr:`~flake8.processor.FileProcessor.indent_level`
+- :attr:`~flake8.processor.FileProcessor.line_number`
+- :attr:`~flake8.processor.FileProcessor.logical_line`
+- :attr:`~flake8.processor.FileProcessor.max_line_length`
+- :attr:`~flake8.processor.FileProcessor.multiline`
+- :attr:`~flake8.processor.FileProcessor.noqa`
+- :attr:`~flake8.processor.FileProcessor.previous_indent_level`
+- :attr:`~flake8.processor.FileProcessor.previous_logical`
+- :attr:`~flake8.processor.FileProcessor.tokens`
+- :attr:`~flake8.processor.FileProcessor.total_lines`
+- :attr:`~flake8.processor.FileProcessor.verbose`
+
+Alternatively, a plugin can accept ``tree`` and ``filename``.
+``tree`` will be a parsed abstract syntax tree that will be used by plugins
+like PyFlakes and McCabe.
+
+Finally, any plugin that has callable attributes ``provide_options`` and
+``register_options`` can parse option information and register new options.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 74810ed..e1b4165 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -19,6 +19,7 @@ Plugin Developer Guide
     :maxdepth: 2
 
     dev/formatters
+    dev/plugin_parameters
     dev/registering_plugins
 
 Developer Guide
diff --git a/flake8/processor.py b/flake8/processor.py
index ab99089..8e6d897 100644
--- a/flake8/processor.py
+++ b/flake8/processor.py
@@ -32,6 +32,7 @@ class FileProcessor(object):
 
     - :attr:`blank_before`
     - :attr:`blank_lines`
+    - :attr:`checker_state`
     - :attr:`indect_char`
     - :attr:`indent_level`
     - :attr:`line_number`