From 5a9c3f375e34beea4c413df738ffe060d4b77cf7 Mon Sep 17 00:00:00 2001
From: shamoon <4887959+shamoon@users.noreply.github.com>
Date: Mon, 8 Dec 2025 14:35:14 -0800
Subject: [PATCH] Improve docstring

---
 src/documents/signals/handlers.py | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/src/documents/signals/handlers.py b/src/documents/signals/handlers.py
index e495631f8..637a5520a 100644
--- a/src/documents/signals/handlers.py
+++ b/src/documents/signals/handlers.py
@@ -679,12 +679,14 @@ def run_workflows(
     original_file: Path | None = None,
 ) -> tuple[DocumentMetadataOverrides, str] | None:
     """
-    Run workflows which match a Document (or ConsumableDocument) for a specific trigger type or a single workflow if given.
+    Execute workflows matching a document for the given trigger. When `overrides` is provided
+    (consumption flow), actions mutate that object and the function returns `(overrides, messages)`.
+    Otherwise actions mutate the actual document and return nothing.
 
-    Assignment or removal actions are either applied directly to the document or an overrides object. If an overrides
-    object is provided, the function returns the object with the applied changes or None if no actions were applied and a string
-    of messages for each action. If no overrides object is provided, the changes are applied directly to the document and the
-    function returns None.
+    Attachments for email/webhook actions use `original_file` when given, otherwise fall back to
+    `document.source_path` (Document) or `document.original_file` (ConsumableDocument).
+
+    Passing `workflow_to_run` skips the workflow query (currently only used by scheduled runs).
     """
 
     use_overrides = overrides is not None