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, 4 insertions, 4 deletions

diff --git a/runtime/lua/vim/lsp/codelens.lua b/runtime/lua/vim/lsp/codelens.lua
index fe581e42ad..ca5a44077e 100644
--- a/runtime/lua/vim/lsp/codelens.lua
+++ b/runtime/lua/vim/lsp/codelens.lua
@@ -22,11 +22,11 @@ local namespaces = setmetatable({}, {
   end;
 })
 
---@private
+---@private
 M.__namespaces = namespaces
 
 
---@private
+---@private
 local function execute_lens(lens, bufnr, client_id)
   local line = lens.range.start.line
   api.nvim_buf_clear_namespace(bufnr, namespaces[client_id], line, line + 1)
@@ -151,7 +151,7 @@ function M.save(lenses, bufnr, client_id)
 end
 
 
---@private
+---@private
 local function resolve_lenses(lenses, bufnr, client_id, callback)
   lenses = lenses or {}
   local num_lens = vim.tbl_count(lenses)
@@ -160,7 +160,7 @@ local function resolve_lenses(lenses, bufnr, client_id, callback)
     return
   end
 
-  --@private
+  ---@private
   local function countdown()
     num_lens = num_lens - 1
     if num_lens == 0 then