Add internal documentation around default formatters

3 files changed, 75 insertions, 18 deletions

diff --git a/docs/source/index.rst b/docs/source/index.rst
index a2bd76a..c8a4f35 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -27,6 +27,7 @@ Developer Guide
 .. toctree::
     :maxdepth: 2
 
+    internal/formatters
     internal/option_handling
     internal/plugin_handling
     internal/utils
diff --git a/docs/source/internal/formatters.rst b/docs/source/internal/formatters.rst
new file mode 100644
index 0000000..caa5718
--- /dev/null
+++ b/docs/source/internal/formatters.rst
@@ -0,0 +1,47 @@
+=====================
+ Built-in Formatters
+=====================
+
+By default Flake8 has two formatters built-in, ``default`` and ``pylint``.
+These correspond to two classes |DefaultFormatter| and |PylintFormatter|.
+
+In Flake8 2.0, pep8 handled formatting of errors and also allowed users to
+specify an arbitrary format string as a parameter to ``--format``. In order
+to allow for this backwards compatibility, Flake8 3.0 made two choices:
+
+#. To not limit a user's choices for ``--format`` to the format class names
+
+#. To make the default formatter attempt to use the string provided by the
+   user if it cannot find a formatter with that name.
+
+Default Formatter
+=================
+
+The |DefaultFormatter| continues to use the same default format string as
+pep8: ``'%(path)s:%(row)d:%(col)d: %(code)s %(text)s'``.
+
+In order to provide the default functionality it overrides two methods:
+
+#. ``after_init``
+
+#. ``format``
+
+The former allows us to inspect the value provided to ``--format`` by the
+user and alter our own format based on that value. The second simply uses
+that format string to format the error.
+
+.. autoclass:: flake8.formatters.default.Default
+    :members:
+
+Pylint Formatter
+================
+
+The |PylintFormatter| simply defines the default Pylint format string from
+pep8: ``'%(path)s:%(row)d: [%(code)s] %(text)s'``.
+
+.. autoclass:: flake8.formatters.default.Pylint
+    :members:
+
+
+.. |DefaultFormatter| replace:: :class:`~flake8.formatters.default.Default`
+.. |PylintFormatter| replace:: :class:`~flake8.formatters.default.Pylint`
diff --git a/flake8/formatting/default.py b/flake8/formatting/default.py
index 036d13f..e0686a0 100644
--- a/flake8/formatting/default.py
+++ b/flake8/formatting/default.py
@@ -2,19 +2,21 @@
 from flake8.formatting import base
 
 
-class Default(base.BaseFormatter):
-    """Default formatter for Flake8.
+class SimpleFormatter(base.BaseFormatter):
+    """Simple abstraction for Default and Pylint formatter commonality.
 
-    This also handles backwards compatibility for people specifying a custom
-    format string.
-    """
+    Sub-classes of this need to define an ``error_format`` attribute in order
+    to succeed. The ``format`` method relies on that attribute and expects the
+    ``error_format`` string to use the old-style formatting strings with named
+    parameters:
 
-    error_format = '%(path)s:%(row)d:%(col)d: %(code)s %(text)s'
+    * code
+    * text
+    * path
+    * row
+    * col
 
-    def after_init(self):
-        """Check for a custom format string."""
-        if self.options.format.lower() != 'default':
-            self.error_format = self.options.format
+    """
 
     def format(self, error):
         """Format and write error out.
@@ -31,15 +33,22 @@ class Default(base.BaseFormatter):
         }
 
 
-class Pylint(Default):
-    """Pylint formatter for Flake8."""
+class Default(SimpleFormatter):
+    """Default formatter for Flake8.
 
-    error_format = '%(path)s:%(row)d: [%(code)s] %(text)s'
+    This also handles backwards compatibility for people specifying a custom
+    format string.
+    """
+
+    error_format = '%(path)s:%(row)d:%(col)d: %(code)s %(text)s'
 
     def after_init(self):
-        """Do not check the value of --format.
+        """Check for a custom format string."""
+        if self.options.format.lower() != 'default':
+            self.error_format = self.options.format
 
-        In the default formatter, this makes sense for backwards
-        compatibility, but it does not make sense here.
-        """
-        pass
+
+class Pylint(SimpleFormatter):
+    """Pylint formatter for Flake8."""
+
+    error_format = '%(path)s:%(row)d: [%(code)s] %(text)s'