docs: make Lua docstrings consistent #15255

The official developer documentation in in :h dev-lua-doc specifies to
use "--@" for special/magic tokens. However, this format is not
consistent with EmmyLua notation (used by some Lua language servers) nor
with the C version of the magic docstring tokens which use three comment
characters.

Further, the code base is currently split between usage of "--@",
"---@", and "--- @". In an effort to remain consistent, change all Lua
magic tokens to use "---@" and update the developer documentation
accordingly.

1 files changed, 5 insertions, 5 deletions

diff --git a/test/helpers.lua b/test/helpers.lua
index 12d9f19187..469aee53f0 100644
--- a/test/helpers.lua
+++ b/test/helpers.lua
@@ -58,9 +58,9 @@ local check_logs_useless_lines = {
 --- Invokes `fn` and includes the tail of `logfile` in the error message if it
 --- fails.
 ---
---@param logfile  Log file, defaults to $NVIM_LOG_FILE or '.nvimlog'
---@param fn       Function to invoke
---@param ...      Function arguments
+---@param logfile  Log file, defaults to $NVIM_LOG_FILE or '.nvimlog'
+---@param fn       Function to invoke
+---@param ...      Function arguments
 local function dumplog(logfile, fn, ...)
   -- module.validate({
   --   logfile={logfile,'s',true},
@@ -102,8 +102,8 @@ end
 
 --- Asserts that `pat` matches one or more lines in the tail of $NVIM_LOG_FILE.
 ---
---@param pat  (string) Lua pattern to search for in the log file.
---@param logfile  (string, default=$NVIM_LOG_FILE) full path to log file.
+---@param pat  (string) Lua pattern to search for in the log file.
+---@param logfile  (string, default=$NVIM_LOG_FILE) full path to log file.
 function module.assert_log(pat, logfile)
   logfile = logfile or os.getenv('NVIM_LOG_FILE') or '.nvimlog'
   local nrlines = 10