From 9ada68118dca394441c2ba0a6bd94ce3ab898d45 Mon Sep 17 00:00:00 2001
From: Ian Cordasco <graffatcolmingov@gmail.com>
Date: Tue, 17 May 2016 20:01:49 -0500
Subject: [PATCH] Finish writing about registering plugin options

---
 docs/source/dev/plugin_parameters.rst | 78 +++++++++++++++++++++++++--
 1 file changed, 75 insertions(+), 3 deletions(-)

diff --git a/docs/source/dev/plugin_parameters.rst b/docs/source/dev/plugin_parameters.rst
index d1d6cb0..17a4dd3 100644
--- a/docs/source/dev/plugin_parameters.rst
+++ b/docs/source/dev/plugin_parameters.rst
@@ -22,7 +22,7 @@ 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 
+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`
@@ -46,8 +46,8 @@ Alternatively, a plugin can accept ``tree`` and ``filename``.
 like PyFlakes and McCabe.
 
 
-Registering and Parsing Options
-===============================
+Registering Options
+===================
 
 Any plugin that has callable attributes ``provide_options`` and
 ``register_options`` can parse option information and register new options.
@@ -61,9 +61,81 @@ which accepts the same parameters as :mod:`optparse` as well as three extra
 boolean parameters:
 
 - ``parse_from_config``
+
+  The command-line option should also be parsed from config files discovered
+  by Flake8.
+
+  .. note::
+
+      This takes the place of appending strings to a list on the
+      :class:`optparse.OptionParser`.
+
 - ``comma_separated_list``
+
+  The value provided to this option is a comma-separated list. After parsing
+  the value, it should be further broken up into a list. This also allows us
+  to handle values like:
+
+  .. code::
+
+      E123,E124,
+      E125,
+        E126
+
 - ``normalize_paths``
 
+  The value provided to this option is a path. It should be normalized to be
+  an absolute path. This can be combined with ``comma_separated_list`` to
+  allow a comma-separated list of paths.
+
+Each of these options works individually or can be combined. Let's look at a
+couple examples from Flake8. In each example, we will have ``option_manager``
+which is an instance of |OptionManager|.
+
+.. code-block:: python
+
+    option_manager.add_option(
+        '--max-line-length', type='int', metavar='n',
+        default=defaults.MAX_LINE_LENGTH, parse_from_config=True,
+        help='Maximum allowed line length for the entirety of this run. '
+             '(Default: %default)',
+    )
+
+Here we are adding the ``--max-line-length`` command-line option which is
+always an integer and will be parsed from the configuration file. Since we
+provide a default, we take advantage of :mod:`optparse`\ 's willingness to
+display that in the help text with ``%default``.
+
+.. code-block:: python
+
+    option_manager.add_option(
+        '--select', metavar='errors', default='',
+        parse_from_config=True, comma_separated_list=True,
+        help='Comma-separated list of errors and warnings to enable.'
+             ' For example, ``--select=E4,E51,W234``. (Default: %default)',
+    )
+
+In adding the ``--select`` command-line option, we're also indicating to the
+|OptionManager| that we want the value parsed from the config files and parsed
+as a comma-separated list.
+
+.. code-block:: python
+
+    option_manager.add_option(
+        '--exclude', metavar='patterns', default=defaults.EXCLUDE,
+        comma_separated_list=True, parse_from_config=True,
+        normalize_paths=True,
+        help='Comma-separated list of files or directories to exclude.'
+             '(Default: %default)',
+    )
+
+Finally, we show an option that uses all three extra flags. Values from
+``--exclude`` will be parsed from the config, converted from a comma-separated
+list, and then each item will be normalized.
+
+For information about other parameters to
+:meth:`~flake8.options.manager.OptionManager.add_option` refer to the
+documentation of :mod:`optparse`.
 
 .. substitutions
 .. |OptionManager| replace:: :class:`~flake8.options.manager.OptionManager`