Add and fix documentation

- Add more documentation around utils functions
- Fix documentation about default formatting plugins
- Add extra documentation of filenames_from predicate parameter
- Add test for the default parameter of flake8.utils.fnmatch

docs/source/internal/formatters.rst

@@ -30,7 +30,7 @@ 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
+.. autoclass:: flake8.formatting.default.Default
     :members:
 
 Pylint Formatter
@@ -39,9 +39,9 @@ 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
+.. autoclass:: flake8.formatting.default.Pylint
     :members:
 
 
-.. |DefaultFormatter| replace:: :class:`~flake8.formatters.default.Default`
-.. |PylintFormatter| replace:: :class:`~flake8.formatters.default.Pylint`
+.. |DefaultFormatter| replace:: :class:`~flake8.formatting.default.Default`
+.. |PylintFormatter| replace:: :class:`~flake8.formatting.default.Pylint`

docs/source/internal/plugin_handling.rst

@@ -98,8 +98,10 @@ API Documentation
     :members:
 
 .. autoclass:: flake8.plugins.manager.Checkers
+    :members:
 
 .. autoclass:: flake8.plugins.manager.Listeners
+    :members: build_notifier
 
 .. autoclass:: flake8.plugins.manager.ReportFormatters
 

docs/source/internal/utils.rst

@@ -45,3 +45,56 @@ strings that should be paths.
 
 This function retrieves and caches the value provided on ``sys.stdin``. This
 allows plugins to use this to retrieve ``stdin`` if necessary.
+
+.. autofunction:: flake8.utils.is_windows
+
+This provides a convenient and explicitly named function that checks if we are
+currently running on a Windows (or ``nt``) operating system.
+
+.. autofunction:: flake8.utils.is_using_stdin
+
+Another helpful function that is named only to be explicit given it is a very
+trivial check, this checks if the user specified ``-`` in their arguments to
+Flake8 to indicate we should read from stdin.
+
+.. autofunction:: flake8.utils.filenames_from
+
+When provided an argument to Flake8, we need to be able to traverse
+directories in a convenient manner. For example, if someone runs
+
+.. code::
+
+    $ flake8 flake8/
+
+Then they want us to check all of the files in the directory ``flake8/``. This
+function will handle that while also handling the case where they specify a
+file like:
+
+.. code::
+
+    $ flake8 flake8/__init__.py
+
+
+.. autofunction:: flake8.utils.fnmatch
+
+The standard library's :func:`fnmatch.fnmatch` is excellent at deciding if a
+filename matches a single pattern. In our use case, however, we typically have
+a list of patterns and want to know if the filename matches any of them. This
+function abstracts that logic away with a little extra logic.
+
+.. autofunction:: flake8.utils.parameters_for
+
+Flake8 analyzes the parameters to plugins to determine what input they are
+expecting. Plugins may expect one of the following:
+
+- ``physical_line`` to receive the line as it appears in the file
+
+- ``logical_line`` to receive the logical line (not as it appears in the file)
+
+- ``tree`` to receive the abstract syntax tree (AST) for the file
+
+We also analyze the rest of the parameters to provide more detail to the
+plugin. This function will return the parameters in a consistent way across
+versions of Python and will handle both classes and functions that are used as
+plugins. Further, if the plugin is a class, it will strip the ``self``
+argument so we can check the parameters of the plugin consistently.

flake8/utils.py

@@ -106,7 +106,8 @@ def filenames_from(arg, predicate=None):
     :param callable predicate:
         Predicate to use to filter out filenames. If the predicate
         returns ``True`` we will exclude the filename, otherwise we
-        will yield it.
+        will yield it. By default, we include every filename
+        generated.
     :returns:
         Generator of paths
     """

tests/unit/test_utils.py

@@ -64,6 +64,12 @@ def test_fnmatch(filename, patterns, expected):
     assert utils.fnmatch(filename, patterns) is expected
 
 
+def test_fnmatch_returns_the_default_with_empty_default():
+    """The default parameter should be returned when no patterns are given."""
+    sentinel = object()
+    assert utils.fnmatch('file.py', [], default=sentinel) is sentinel
+
+
 def test_filenames_from_a_directory():
     """Verify that filenames_from walks a directory."""
     filenames = list(utils.filenames_from('flake8/'))