Add documentation around plugin notifications and pyflakes

1 files changed, 31 insertions, 0 deletions

diff --git a/docs/source/internal/plugin_handling.rst b/docs/source/internal/plugin_handling.rst
index e217497..e430bfb 100644
--- a/docs/source/internal/plugin_handling.rst
+++ b/docs/source/internal/plugin_handling.rst
@@ -56,6 +56,33 @@ These are used to interact with each of the types of plugins individually.
 Notifying Listener Plugins
 --------------------------
 
+One of the interesting challenges with allowing plugins to be notified each
+time an error or warning is emitted by a checker is finding listeners quickly
+and efficiently. It makes sense to allow a listener to listen for a certain
+class of warnings or just a specific warning. As such, we need to allow all
+plugins that listen to a specific warning or class to be notified. For
+example, someone might register a listener for ``E1`` and another for ``E111``
+if ``E111`` is triggered by the code, both listeners should be notified.
+If ``E112`` is returned, then only ``E1`` (and any other listeners) would be
+notified.
+
+To implement this goal, we needed an object to store listeners in that would
+allow for efficient look up - a Trie (or Prefix Tree). Given that none of the
+existing packages on PyPI allowed for storing data on each node of the trie,
+it was left up to write our own as :class:`~flake8.plugins._trie.Trie`. On
+top of that we layer our :class:`~flake8.plugins.notifier.Notifier` class.
+
+Now when Flake8 receives an error or warning, we can easily call the
+:meth:`~flake8.plugins.notifier.Notifier.notify` method and let plugins act on
+that knowledge.
+
+Default Plugins
+---------------
+
+Finally, Flake8 has always provided its own plugin shim for Pyflakes. As part
+of that we carry our own shim in-tree and now store that in
+:mod:`flake8.plugins.pyflakes`.
+
 API Documentation
 -----------------
 
@@ -76,6 +103,10 @@ API Documentation
 
 .. autoclass:: flake8.plugins.manager.ReportFormatters
 
+.. autoclass:: flake8.plugins.notifier.Notifier
+
+.. autoclass:: flake8.plugins._trie.Trie
+
 .. |PluginManager| replace:: :class:`~flake8.plugins.manager.PluginManager`
 .. |Plugin| replace:: :class:`~flake8.plugins.manager.Plugin`
 .. |PTM| replace:: :class:`~flake8.plugins.manager.PluginTypeManager`