From fc1b58899e0592e873d97a71982b76254c3584fd Mon Sep 17 00:00:00 2001
From: Optical Disc <88067218+opticaldisc@users.noreply.github.com>
Date: Wed, 26 Nov 2025 22:36:50 -0800
Subject: [PATCH] Add more detail about --@ lines in the Lua API doc.

Includes a block of examples showing what will work and what will not.
---
 docs/dev/Lua API.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/dev/Lua API.rst b/docs/dev/Lua API.rst
index a4a039f409..cc7a90bb3f 100644
--- a/docs/dev/Lua API.rst	
+++ b/docs/dev/Lua API.rst	
@@ -7468,6 +7468,15 @@ Importing scripts
 
       --@ module = true
 
+     In order to be recognized, this line **must** begin with ``--@`` with no
+     whitespace characters before it::
+
+      --@ module = true   OK
+      --@module = true    OK
+      -- @module = true   NOT OK (no --@ found due to space after --)
+       --@module = true   NOT OK (leading space, --@ is not at the beginning of the line)
+      ---@module = true   NOT OK (leading dash, --@ is not at the beginning of the line)
+
   2. Include a check for ``dfhack_flags.module``, and avoid running any code
      that has side-effects if this flag is true. For instance::