From 82129c2b8f04f413d7130e32608a671353848584 Mon Sep 17 00:00:00 2001
From: dgw <dgw@technobabbl.es>
Date: Wed, 26 Jan 2022 19:17:47 -0600
Subject: [PATCH] docs: add some more info about `allow_bots`, `echo`, and
 `unblockable`

These didn't get any brief mention on the "Anatomy of a plugin" page,
like most of their siblings already had. It seemed only fair.

Also added a gotcha to the `echo` decorator's docs.
---
 docs/source/plugin/anatomy.rst | 26 ++++++++++++++++++++++++++
 sopel/plugin.py                |  7 +++++++
 2 files changed, 33 insertions(+)

diff --git a/docs/source/plugin/anatomy.rst b/docs/source/plugin/anatomy.rst
index 09186d652f..8828821f9c 100644
--- a/docs/source/plugin/anatomy.rst
+++ b/docs/source/plugin/anatomy.rst
@@ -124,6 +124,32 @@ Example::
 A rule with rate-limiting can return :const:`sopel.plugin.NOLIMIT` to let the
 user try again after a failed command, e.g. if a required argument is missing.
 
+Bypassing restrictions
+----------------------
+
+By default, a :term:`Rule` will not trigger on messages from Sopel itself,
+other users that are flagged as bots, or users who are
+:ref:`ignored <Ignore User>` or :ref:`rate-limited <Rate limiting>`. In
+certain cases, it might be desirable to bypass these defaults using one or
+more of these decorators:
+
+* :func:`~sopel.plugin.allow_bots`: the rule will receive events from other
+  users flagged as bots (like Sopel itself)
+* :func:`~sopel.plugin.echo`: the rule will receive Sopel's own actions (e.g.
+  the output of any calls to :func:`bot.say <sopel.bot.Sopel.say>`)
+* :func:`~sopel.plugin.unblockable`: the rule will ignore rate-limiting or
+  nick/host blocks and always process the event
+
+For example, Sopel itself uses the :func:`~sopel.plugin.unblockable` decorator
+to track joins/parts from everyone, always, so plugins can *always* access
+data about any user in any channel.
+
+.. important::
+
+   The :func:`~sopel.plugin.echo` decorator will send *anything* Sopel says
+   (that matches the rule) to the decorated callable, *including output from
+   the callable itself*. Be careful not to create a feedback loop.
+
 Rule labels
 -----------
 
diff --git a/sopel/plugin.py b/sopel/plugin.py
index 76b667a499..84e84cbb8e 100644
--- a/sopel/plugin.py
+++ b/sopel/plugin.py
@@ -493,6 +493,13 @@ def echo(
 
     This decorator can be used to listen in on the messages that Sopel is
     sending and react accordingly.
+
+    .. important::
+
+        The decorated callable will receive *all* matching messages that Sopel
+        sends, including output from the same callable. Take care to avoid
+        creating feedback loops when using this feature.
+
     """
     def add_attribute(function):
         function.echo = True