docs: remove "#" comment char in @return

Everything after a "#" char is a "description" comment, i.e. luals won't
treat it as a type, name, etc. But "#" should not be present in the
generated docs (such as :help docs).
https://github.com/LuaLS/lua-language-server/wiki/Annotations#return

4 files changed, 13 insertions, 7 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5d2c675ad9..18603321fb 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -289,7 +289,8 @@ For convenience you can filter the regeneration by target (api, lua, lsp) using
 
 ### Lua docstrings
 
-Lua documentation uses a subset of [EmmyLua] annotations. See [:help dev-doc-lua][dev-doc-lua].
+Use [LuaLS] annotations in Lua docstrings to annotate parameter types, return
+types, etc. See [:help dev-doc-lua][dev-doc-lua].
 
 - The template for function documentation is:
   ```lua
@@ -340,7 +341,7 @@ as context, use the `-W` argument as well.
 [conventional_commits]: https://www.conventionalcommits.org
 [dev-doc-guide]: https://neovim.io/doc/user/develop.html#dev-doc
 [dev-doc-lua]: https://neovim.io/doc/user/develop.html#dev-lua-doc
-[EmmyLua]: https://github.com/sumneko/lua-language-server/wiki/Annotations
+[LuaLS]: https://github.com/LuaLS/lua-language-server/wiki/Annotations
 [gcc-warnings]: https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html
 [gh]: https://cli.github.com/
 [git-bisect]: http://git-scm.com/book/en/v2/Git-Tools-Debugging-with-Git
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 25f570e38a..b3f7d1fadc 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -226,6 +226,7 @@ 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`
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index b087156766..94a2c0d45e 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1569,7 +1569,7 @@ vim.deprecate({name}, {alternative}, {version}, {plugin}, {backtrace})
       • {backtrace}    boolean|nil Prints backtrace. Defaults to true.
 
     Return: ~
-        (string|nil) # Deprecated message, or nil if no message was shown.
+        (string|nil) Deprecated message, or nil if no message was shown.
 
 vim.inspect                                                    *vim.inspect()*
     Gets a human-readable representation of the given object.
@@ -1693,7 +1693,7 @@ vim.print({...})                                                 *vim.print()*
 <
 
     Return: ~
-        any # given arguments.
+        any given arguments.
 
     See also: ~
       • |vim.inspect()|
@@ -2080,7 +2080,7 @@ vim.spairs({t})                                                 *vim.spairs()*
       • {t}  (table) Dict-like table
 
     Return: ~
-        _ iterator over sorted keys and their values
+        iterator over sorted keys and their values
 
     See also: ~
       • Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua
@@ -2545,8 +2545,8 @@ vim.ui.open({path})                                            *vim.ui.open()*
       • {path}  (string) Path or URL to open
 
     Return (multiple): ~
-        SystemCompleted|nil # Command result, or nil if not found.
-        (string|nil) # Error message on failure
+        SystemCompleted|nil Command result, or nil if not found.
+        (string|nil) Error message on failure
 
     See also: ~
       • |vim.system()|
diff --git a/scripts/lua2dox.lua b/scripts/lua2dox.lua
index 9a666ea629..01bb8ab57a 100644
--- a/scripts/lua2dox.lua
+++ b/scripts/lua2dox.lua
@@ -154,6 +154,8 @@ local function removeCommentFromLine(line)
   return line:sub(1, pos_comment - 1), line:sub(pos_comment)
 end
 
+--- Processes "@…" directives in a docstring line.
+---
 --- @param line string
 --- @param generics table<string,string>
 --- @return string?
@@ -206,6 +208,8 @@ local function process_magic(line, generics)
       magic = magic:gsub('^return%s+.*%((' .. type .. ')%)', 'return %1')
       magic = magic:gsub('^return%s+.*%((' .. type .. '|nil)%)', 'return %1')
     end
+    -- Remove first "#" comment char, if any. https://github.com/LuaLS/lua-language-server/wiki/Annotations#return
+    magic = magic:gsub('# ', '', 1)
     -- handle the return of vim.spell.check
     magic = magic:gsub('({.*}%[%])', '`%1`')
     magic_split = vim.split(magic, ' ', { plain = true })