Document the types of plugins and expected results

docs/source/plugin-development/checkers.rst

@@ -0,0 +1,106 @@
+.. _checker-plugins:
+
+===============
+Checker Plugins
+===============
+
+A |Flake8| checker plugin needs to have a registered entry point. This entry
+point must reference a callable object.
+
+
+Declaring the type of plugin
+============================
+
+Flake8 uses certain key parameters to determine the kind of plugin this is and
+how it needs to call it:
+
+* If it has a parameter called ``tree`` then this plugin is considered to be an
+  AST checker plugin. It will be called once per file and it will receive the
+  parsed AST of the file as the ``tree`` parameter.  If this entry point
+  references a class, then the call will construct an instance of such class,
+  and Flake8 will then call the ``run()`` method on the created object to get
+  results.
+* If the callable has a parameter called ``physical_line`` then whatever the
+  entry point references is called for each physical line and the call is
+  expected to yield results directly.
+* If the callable has a parameter called ``logical_line`` then the callable
+  referred to by the entry point will be called from Flake8 with each logical
+  line and is expected to yield results.
+
+
+.. note::
+    Class-style plugins are only supported for AST checker (*tree*) plugins.
+
+
+The Results
+===========
+
+Tree plugins
+------------
+
+A tree plugins can be a function or a class. If it is a function, it must take
+a parameter called ``tree``. If it is a class, then the ``__init__`` method
+must take this parameter.
+
+For a class based plugin, the ``run`` method is in charge of yielding results.
+For functions, they must deliver results directly.
+
+Flake8 expects the result of running these plugins to be an iterable of tuples,
+each of which contain the following:
+
+* An ``int`` with the line number where the issue appears
+
+* An ``int`` with the offset within the line where the issue appears (column)
+
+* A ``str`` with the error message
+
+* The source of the error (typically the name of the plugin). Although this
+  field is not used by |Flake8|, it must be present in each tuple
+
+
+Physical Line plugins
+---------------------
+
+A Physical Line plugin must be callable, it must take a parameter called
+``physical_line`` and it must return the result of checking the passed physical
+line.
+
+Flake8 expects the result of this call to be an iterable of tuples, each
+containing the following:
+
+* An ``int`` with the offset within the line where the reported issue appears
+
+* A ``str`` with the error message
+
+
+Logical Line Plugins
+--------------------
+
+A Logical Line plugin must be callable, it must take a parameter called
+``logical_line`` and it must return the result of checking the passed logical
+line.
+
+Flake8 expects the result of this call to be an iterable of tuples, each
+containing the following:
+
+* An ``int`` with the offset within the logical line where the reported issue
+  appears
+
+* A ``str`` with the error message
+
+|Flake8| will take care of the conversion from the reported offset on the
+logical line to a physical line and physical column pair before it outputs
+errors to the user.
+
+
+Video Tutorial
+==============
+
+Here's a tutorial which goes over building an AST checking plugin from scratch:
+
+.. raw:: html
+
+    <div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%; height: auto; margin-bottom: 1em;">
+        <iframe src="https://www.youtube.com/embed/ot5Z4KQPBL8" frameborder="0" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe>
+    </div>
+

docs/source/plugin-development/formatters.rst

@@ -4,7 +4,7 @@
  Developing a Formatting Plugin for Flake8
 ===========================================
 
-|Flake8| allowed for custom formatting plugins in version
+|Flake8| allowes for custom formatting plugins since version
 3.0.0. Let's write a plugin together:
 
 .. code-block:: python

docs/source/plugin-development/getting-started.rst

@@ -0,0 +1,39 @@
+.. _getting-started:
+
+===============
+Getting Started
+===============
+
+To get started writing a |Flake8| :term:`plugin` you first need:
+
+- An idea for a plugin
+
+- An available package name on PyPI
+
+- One or more versions of Python installed
+
+- A text editor or IDE of some kind
+
+- An idea of what *kind* of plugin you want to build:
+
+  * Formatter
+
+  * Check
+
+Once you've gathered these things, you can get started.
+
+All plugins for |Flake8| must be registered via `entry points`_. In this
+section we cover:
+
+- How to register your plugin so |Flake8| can find it
+
+- How to make |Flake8| provide your check plugin with information (via
+  command-line flags, function/class parameters, etc.)
+
+- How to make a formatter plugin
+
+- How to write your check plugin so that it works with |Flake8| 2.x and 3.x
+
+
+.. _entry points:
+    https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points

docs/source/plugin-development/index.rst

@@ -9,60 +9,15 @@ documentation in this section may reference third-party documentation to
 reduce duplication and to point you, the developer, towards the authoritative
 documentation for those pieces.
 
-Getting Started
-===============
-
-To get started writing a |Flake8| :term:`plugin` you first need:
-
-- An idea for a plugin
-
-- An available package name on PyPI
-
-- One or more versions of Python installed
-
-- A text editor or IDE of some kind
-
-- An idea of what *kind* of plugin you want to build:
-
-  * Formatter
-
-  * Check
-
-Once you've gathered these things, you can get started.
-
-All plugins for |Flake8| must be registered via `entry points`_. In this
-section we cover:
-
-- How to register your plugin so |Flake8| can find it
-
-- How to make |Flake8| provide your check plugin with information (via
-  command-line flags, function/class parameters, etc.)
-
-- How to make a formatter plugin
-
-- How to write your check plugin so that it works with |Flake8| 2.x and 3.x
-
-
-Video Tutorial
-==============
-
-Here's a tutorial which goes over building an ast checking plugin from scratch:
-
-.. raw:: html
-
-    <div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%; height: auto; margin-bottom: 1em;">
-        <iframe src="https://www.youtube.com/embed/ot5Z4KQPBL8" frameborder="0" allowfullscreen style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"></iframe>
-    </div>
 
 
 .. toctree::
     :caption: Plugin Developer Documentation
     :maxdepth: 2
 
+    getting-started
+    plugin-types
     registering-plugins
     plugin-parameters
+    checkers
     formatters
-
-
-.. _entry points:
-    https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points

docs/source/plugin-development/plugin-types.rst

@@ -0,0 +1,22 @@
+.. _plugin-types:
+
+================
+Types of Plugins
+================
+
+|Flake8| supports two types of plugins:
+
+- **Check Plugins**: Plugins that contribute additional code checks that will
+  get reported together with |Flake8|'s default checks. In these, there are
+  three different ways these checks can happen:
+
+  * Once per file. Your checker plugin will be called once per file and it will
+    receive a parsed AST for the file.
+
+  * Once per physical line.
+
+  * Once per logical line.
+
+- **Report Plugins**: Plugins that receive errors and modify the way these are
+  reported. They can take care of formatting, filtering, aggregating, etc.
+