From 41ea4e89074f8a3b44c63aa33ca116f215d23503 Mon Sep 17 00:00:00 2001
From: Talley Lambert <talley.lambert@gmail.com>
Date: Thu, 17 Aug 2023 09:40:06 -0400
Subject: [PATCH] docs: document signals blocked (#186)

---
 docs/utilities/signal_utils.md |  3 +++
 src/superqt/utils/_misc.py     | 19 ++++++++++++++++++-
 2 files changed, 21 insertions(+), 1 deletion(-)
 create mode 100644 docs/utilities/signal_utils.md

diff --git a/docs/utilities/signal_utils.md b/docs/utilities/signal_utils.md
new file mode 100644
index 0000000..cf62970
--- /dev/null
+++ b/docs/utilities/signal_utils.md
@@ -0,0 +1,3 @@
+# Signal Utilities
+
+::: superqt.utils.signals_blocked
diff --git a/src/superqt/utils/_misc.py b/src/superqt/utils/_misc.py
index 085f191..ef4b33e 100644
--- a/src/superqt/utils/_misc.py
+++ b/src/superqt/utils/_misc.py
@@ -7,7 +7,24 @@ if TYPE_CHECKING:
 
 @contextmanager
 def signals_blocked(obj: "QObject") -> Iterator[None]:
-    """Context manager to temporarily block signals emitted by QObject: `obj`."""
+    """Context manager to temporarily block signals emitted by QObject: `obj`.
+
+    Parameters
+    ----------
+    obj : QObject
+        The QObject whose signals should be blocked.
+
+    Examples
+    --------
+    ```python
+    from qtpy.QtWidgets import QSpinBox
+    from superqt import signals_blocked
+
+    spinbox = QSpinBox()
+    with signals_blocked(spinbox):
+        spinbox.setValue(10)
+    ```
+    """
     previous = obj.blockSignals(True)
     try:
         yield