docs: Lua docstrings guidance #25345

Recommend adding a space after i.e. `--- @see`.

The "space" variant is common for the vast majority of docstring formats
such as doxygen, javadoc and typescript.

2 files changed, 12 insertions, 11 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7eed75f0d4..2128b3af13 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -308,11 +308,11 @@ types, etc. See [:help dev-doc-lua][dev-doc-lua].
   ---
   --- {Long explanation}
   ---
-  ---@param arg1 type {description}
-  ---@param arg2 type {description}
+  --- @param arg1 type {description}
+  --- @param arg2 type {description}
   --- ...
   ---
-  ---@return type {description}
+  --- @return type {description}
   ```
 - If possible, add type information (`table`, `string`, `number`, ...). Multiple valid types are separated by a bar (`string|table`). Indicate optional parameters via `type|nil`.
 - If a function in your Lua module should _not_ be documented, add `@nodoc`.
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index f4c581fabe..c88b8a88c3 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -232,10 +232,11 @@ Lua documentation lives in the source code, as docstrings on the function
 definitions.  The |lua-vim| :help is generated from the docstrings.
 
 Docstring format:
-- Use LuaLS annotations: https://github.com/LuaLS/lua-language-server/wiki/Annotations
-- Lines in the main description start with `---`
-- Special tokens start with `---@` followed by the token name:
-  `---@see`, `---@param`, `---@returns`
+- Use LuaLS annotations (with minor adjustments, which will be explained
+  below): https://luals.github.io/wiki/annotations/
+- Lines in the main description start with `--- `
+- Special tokens start with `--- @` followed by the token name: `--- @see`,
+  `--- @param`, `--- @returns`. Note the space between `---` and `@`.
 - Limited markdown is supported.
   - List-items start with `-` (useful to nest or "indent")
 - Use ``` for code samples.
@@ -258,11 +259,11 @@ vim.paste in runtime/lua/vim/_editor.lua like this: >
     --- end)()
     --- ```
     ---
-    ---@see |paste|
+    --- @see |paste|
     ---
-    ---@param lines  ...
-    ---@param phase  ...
-    ---@returns false if client should cancel the paste.
+    --- @param lines  ...
+    --- @param phase  ...
+    --- @returns false if client should cancel the paste.
 
 
 LUA STDLIB DESIGN GUIDELINES				*dev-lua*