Document Legacy API

2 files changed, 106 insertions, 2 deletions

diff --git a/docs/source/user/python-api.rst b/docs/source/user/python-api.rst
index 214565d..2c576ae 100644
--- a/docs/source/user/python-api.rst
+++ b/docs/source/user/python-api.rst
@@ -7,5 +7,97 @@
 When it does it will be located in :mod:`flake8.api` and that will
 be documented here.
 
-.. automodule:: flake8.api
+
+Legacy API
+==========
+
+When |Flake8| broke it's hard dependency on the tricky internals of
+pycodestyle, it lost the easy backwards compatibility as well. To help
+existing users of that API we have :mod:`flake8.api.legacy`. This module
+includes a couple classes (which are documented below) and a function.
+
+The main usage that the developers of Flake8 observed was using the
+:func:`~flake8.api.legacy.get_style_guide` function and then calling
+:meth:`~flake8.api.legacy.StyleGuide.check_files`. To a lesser extent,
+people also seemed to use the :meth:`~flake8.api.legacy.Report.get_statistics`
+method on what ``check_files`` returns. We then sought to preserve that
+API in this module.
+
+Let's look at an example piece of code together:
+
+.. code-block:: python
+
+    from flake8.api import legacy as flake8
+
+
+    style_guide = flake8.get_style_guide(ignore=['E24', 'W503'])
+    report = style_guide.check_files([...])
+    assert report.get_statistics('E') == [], 'Flake8 found violations'
+
+This represents the basic universal usage of all existing Flake8 2.x
+integrations. Each example we found was obviously slightly different,
+but this is kind of the gist, so let's walk through this.
+
+Everything that is backwards compatible for our API is in the
+:mod:`flake8.api.legacy` submodule. This is to indicate, clearly, that
+the old API is being used.
+
+We create a |StyleGuide| by calling |style_guide|.  We can pass options
+to |style_guide| that correspond to the command-line options one might use.
+For example, we can pass ``ignore``, ``select``, ``exclude``, ``format``, etc.
+Our legacy API, does not enforce legacy behaviour, so we can combine
+``ignore`` and ``select`` like we might on the command-line, e.g.,
+
+.. code-block:: python
+
+    style_guide = flake8.get_style_guide(
+        ignore=['E24', 'W5'],
+        select=['E', 'W', 'F'],
+        format='pylint',
+    )
+
+Once we have our |StyleGuide| we can use the same methods that we used before,
+namely
+
+.. automethod:: flake8.api.legacy.StyleGuide.check_files
+
+.. automethod:: flake8.api.legacy.StyleGuide.excluded
+
+.. automethod:: flake8.api.legacy.StyleGuide.init_report
+
+.. automethod:: flake8.api.legacy.StyleGuide.input_file
+
+.. warning::
+
+    These are not *perfectly* backwards compatible. Not all arguments are
+    respsected, and some of the types necessary for something to work have
+    changed.
+
+Most people, we observed, were using
+:meth:`~flake8.api.legacy.StyleGuide.check_files`. You can use this to specify
+a list of filenames or directories to check. In |Flake8| 3.0, however, we
+return a different object that has similar methods. We return a |Report| which
+has the method
+
+.. automethod:: flake8.api.legacy.Report.get_statistics
+
+Most usage of this method that we noted was as documented above. Keep in mind,
+however, that it provides a list of strings and not anything more maleable.
+
+
+Autogenerated Legacy Documentation
+----------------------------------
+
+.. automodule:: flake8.api.legacy
     :members:
+
+.. autoclass:: flake8.api.legacy.StyleGuide
+    :members: options, paths
+
+.. autoclass:: flake8.api.legacy.Report
+    :members: total_errors
+
+
+.. |style_guide| replace:: :func:`flake8.api.legacy.get_style_guide`
+.. |StyleGuide| replace:: :class:`flake8.api.legacy.StyleGuide`
+.. |Report| replace:: :class:`flake8.api.legacy.Report`
diff --git a/src/flake8/api/legacy.py b/src/flake8/api/legacy.py
index a6c3b6a..84e0b03 100644
--- a/src/flake8/api/legacy.py
+++ b/src/flake8/api/legacy.py
@@ -156,6 +156,10 @@ class Report(object):
         There are important changes in how this object behaves compared to
         the object provided in Flake8 2.x.
 
+    .. warning::
+
+        This should not be instantiated by users.
+
     .. versionchanged:: 3.0.0
     """
 
@@ -174,7 +178,15 @@ class Report(object):
         return self._application.result_count
 
     def get_statistics(self, violation):
-        """Get the number of occurences of a violation."""
+        """Get the list of occurences of a violation.
+
+        :returns:
+            List of occurrences of a violation formatted as:
+            {Count} {Error Code} {Message}, e.g.,
+            ``8 E531 Some error message about the error``
+        :rtype:
+            list
+        """
         return [
             '{} {} {}'.format(s.count, s.error_code, s.message)
             for s in self._stats.statistics_for(violation)