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.

runtime/lua/vim/lsp/rpc.lua

@@ -5,11 +5,11 @@ local protocol = require('vim.lsp.protocol')
 local validate, schedule, schedule_wrap = vim.validate, vim.schedule, vim.schedule_wrap
 
 -- TODO replace with a better implementation.
---@private
+---@private
 --- Encodes to JSON.
 ---
---@param data (table) Data to encode
---@returns (string) Encoded object
+---@param data (table) Data to encode
+---@returns (string) Encoded object
 local function json_encode(data)
   local status, result = pcall(vim.fn.json_encode, data)
   if status then
@@ -18,11 +18,11 @@ local function json_encode(data)
     return nil, result
   end
 end
---@private
+---@private
 --- Decodes from JSON.
 ---
---@param data (string) Data to decode
---@returns (table) Decoded JSON object
+---@param data (string) Data to decode
+---@returns (table) Decoded JSON object
 local function json_decode(data)
   local status, result = pcall(vim.fn.json_decode, data)
   if status then
@@ -32,10 +32,10 @@ local function json_decode(data)
   end
 end
 
---@private
+---@private
 --- Checks whether a given path exists and is a directory.
---@param filename (string) path to check
---@returns (bool)
+---@param filename (string) path to check
+---@returns (bool)
 local function is_dir(filename)
   local stat = vim.loop.fs_stat(filename)
   return stat and stat.type == 'directory' or false
@@ -43,7 +43,7 @@ end
 
 local NIL = vim.NIL
 
---@private
+---@private
 local recursive_convert_NIL
 recursive_convert_NIL = function(v, tbl_processed)
   if v == NIL then
@@ -63,15 +63,15 @@ recursive_convert_NIL = function(v, tbl_processed)
   return v
 end
 
---@private
+---@private
 --- Returns its argument, but converts `vim.NIL` to Lua `nil`.
---@param v (any) Argument
---@returns (any)
+---@param v (any) Argument
+---@returns (any)
 local function convert_NIL(v)
   return recursive_convert_NIL(v, {})
 end
 
---@private
+---@private
 --- Merges current process env with the given env and returns the result as
 --- a list of "k=v" strings.
 ---
@@ -81,8 +81,8 @@ end
 ---  in:    { PRODUCTION="false", PATH="/usr/bin/", PORT=123, HOST="0.0.0.0", }
 ---  out:   { "PRODUCTION=false", "PATH=/usr/bin/", "PORT=123", "HOST=0.0.0.0", }
 --- </pre>
---@param env (table) table of environment variable assignments
---@returns (table) list of `"k=v"` strings
+---@param env (table) table of environment variable assignments
+---@returns (table) list of `"k=v"` strings
 local function env_merge(env)
   if env == nil then
     return env
@@ -97,11 +97,11 @@ local function env_merge(env)
   return final_env
 end
 
---@private
+---@private
 --- Embeds the given string into a table and correctly computes `Content-Length`.
 ---
---@param encoded_message (string)
---@returns (table) table containing encoded message and `Content-Length` attribute
+---@param encoded_message (string)
+---@returns (table) table containing encoded message and `Content-Length` attribute
 local function format_message_with_content_length(encoded_message)
   return table.concat {
     'Content-Length: '; tostring(#encoded_message); '\r\n\r\n';
@@ -109,11 +109,11 @@ local function format_message_with_content_length(encoded_message)
   }
 end
 
---@private
+---@private
 --- Parses an LSP Message's header
 ---
---@param header: The header to parse.
---@returns Parsed headers
+---@param header: The header to parse.
+---@returns Parsed headers
 local function parse_headers(header)
   if type(header) ~= 'string' then
     return nil
@@ -141,7 +141,7 @@ end
 -- case insensitive pattern.
 local header_start_pattern = ("content"):gsub("%w", function(c) return "["..c..c:upper().."]" end)
 
---@private
+---@private
 --- The actual workhorse.
 local function request_parser_loop()
   local buffer = '' -- only for header part
@@ -203,8 +203,8 @@ local client_errors = vim.tbl_add_reverse_lookup {
 
 --- Constructs an error message from an LSP error object.
 ---
---@param err (table) The error object
---@returns (string) The formatted error message
+---@param err (table) The error object
+---@returns (string) The formatted error message
 local function format_rpc_error(err)
   validate {
     err = { err, 't' };
@@ -233,9 +233,9 @@ end
 
 --- Creates an RPC response object/table.
 ---
---@param code RPC error code defined in `vim.lsp.protocol.ErrorCodes`
---@param message (optional) arbitrary message to send to server
---@param data (optional) arbitrary data to send to server
+---@param code RPC error code defined in `vim.lsp.protocol.ErrorCodes`
+---@param message (optional) arbitrary message to send to server
+---@param data (optional) arbitrary data to send to server
 local function rpc_response_error(code, message, data)
   -- TODO should this error or just pick a sane error (like InternalError)?
   local code_name = assert(protocol.ErrorCodes[code], 'Invalid RPC error code')
@@ -250,38 +250,38 @@ end
 
 local default_dispatchers = {}
 
---@private
+---@private
 --- Default dispatcher for notifications sent to an LSP server.
 ---
---@param method (string) The invoked LSP method
---@param params (table): Parameters for the invoked LSP method
+---@param method (string) The invoked LSP method
+---@param params (table): Parameters for the invoked LSP method
 function default_dispatchers.notification(method, params)
   local _ = log.debug() and log.debug('notification', method, params)
 end
---@private
+---@private
 --- Default dispatcher for requests sent to an LSP server.
 ---
---@param method (string) The invoked LSP method
---@param params (table): Parameters for the invoked LSP method
---@returns `nil` and `vim.lsp.protocol.ErrorCodes.MethodNotFound`.
+---@param method (string) The invoked LSP method
+---@param params (table): Parameters for the invoked LSP method
+---@returns `nil` and `vim.lsp.protocol.ErrorCodes.MethodNotFound`.
 function default_dispatchers.server_request(method, params)
   local _ = log.debug() and log.debug('server_request', method, params)
   return nil, rpc_response_error(protocol.ErrorCodes.MethodNotFound)
 end
---@private
+---@private
 --- Default dispatcher for when a client exits.
 ---
---@param code (number): Exit code
---@param signal (number): Number describing the signal used to terminate (if
+---@param code (number): Exit code
+---@param signal (number): Number describing the signal used to terminate (if
 ---any)
 function default_dispatchers.on_exit(code, signal)
   local _ = log.info() and log.info("client_exit", { code = code, signal = signal })
 end
---@private
+---@private
 --- Default dispatcher for client errors.
 ---
---@param code (number): Error code
---@param err (any): Details about the error
+---@param code (number): Error code
+---@param err (any): Details about the error
 ---any)
 function default_dispatchers.on_error(code, err)
   local _ = log.error() and log.error('client_error:', client_errors[code], err)
@@ -290,25 +290,25 @@ end
 --- Starts an LSP server process and create an LSP RPC client object to
 --- interact with it.
 ---
---@param cmd (string) Command to start the LSP server.
---@param cmd_args (table) List of additional string arguments to pass to {cmd}.
---@param dispatchers (table, optional) Dispatchers for LSP message types. Valid
+---@param cmd (string) Command to start the LSP server.
+---@param cmd_args (table) List of additional string arguments to pass to {cmd}.
+---@param dispatchers (table, optional) Dispatchers for LSP message types. Valid
 ---dispatcher names are:
 --- - `"notification"`
 --- - `"server_request"`
 --- - `"on_error"`
 --- - `"on_exit"`
---@param extra_spawn_params (table, optional) Additional context for the LSP
+---@param extra_spawn_params (table, optional) Additional context for the LSP
 --- server process. May contain:
 --- - {cwd} (string) Working directory for the LSP server process
 --- - {env} (table) Additional environment variables for LSP server process
---@returns Client RPC object.
+---@returns Client RPC object.
 ---
---@returns Methods:
+---@returns Methods:
 --- - `notify()` |vim.lsp.rpc.notify()|
 --- - `request()` |vim.lsp.rpc.request()|
 ---
---@returns Members:
+---@returns Members:
 --- - {pid} (number) The LSP server's PID.
 --- - {handle} A handle for low-level interaction with the LSP server process
 ---   |vim.loop|.
@@ -358,10 +358,10 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
 
   local handle, pid
   do
-    --@private
+    ---@private
     --- Callback for |vim.loop.spawn()| Closes all streams and runs the `on_exit` dispatcher.
-    --@param code (number) Exit code
-    --@param signal (number) Signal that was used to terminate (if any)
+    ---@param code (number) Exit code
+    ---@param signal (number) Signal that was used to terminate (if any)
     local function onexit(code, signal)
       stdin:close()
       stdout:close()
@@ -385,12 +385,12 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
     end
   end
 
-  --@private
+  ---@private
   --- Encodes {payload} into a JSON-RPC message and sends it to the remote
   --- process.
   ---
-  --@param payload (table) Converted into a JSON string, see |json_encode()|
-  --@returns true if the payload could be scheduled, false if the main event-loop is in the process of closing.
+  ---@param payload (table) Converted into a JSON string, see |json_encode()|
+  ---@returns true if the payload could be scheduled, false if the main event-loop is in the process of closing.
   local function encode_and_send(payload)
     local _ = log.debug() and log.debug("rpc.send.payload", payload)
     if handle == nil or handle:is_closing() then return false end
@@ -406,9 +406,9 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
   -- `start()`
   --
   --- Sends a notification to the LSP server.
-  --@param method (string) The invoked LSP method
-  --@param params (table): Parameters for the invoked LSP method
-  --@returns (bool) `true` if notification could be sent, `false` if not
+  ---@param method (string) The invoked LSP method
+  ---@param params (table): Parameters for the invoked LSP method
+  ---@returns (bool) `true` if notification could be sent, `false` if not
   local function notify(method, params)
     return encode_and_send {
       jsonrpc = "2.0";
@@ -417,7 +417,7 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
     }
   end
 
-  --@private
+  ---@private
   --- sends an error object to the remote LSP process.
   local function send_response(request_id, err, result)
     return encode_and_send {
@@ -433,10 +433,10 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
   --
   --- Sends a request to the LSP server and runs {callback} upon response.
   ---
-  --@param method (string) The invoked LSP method
-  --@param params (table) Parameters for the invoked LSP method
-  --@param callback (function) Callback to invoke
-  --@returns (bool, number) `(true, message_id)` if request could be sent, `false` if not
+  ---@param method (string) The invoked LSP method
+  ---@param params (table) Parameters for the invoked LSP method
+  ---@param callback (function) Callback to invoke
+  ---@returns (bool, number) `(true, message_id)` if request could be sent, `false` if not
   local function request(method, params, callback)
     validate {
       callback = { callback, 'f' };
@@ -463,13 +463,13 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
     end
   end)
 
-  --@private
+  ---@private
   local function on_error(errkind, ...)
     assert(client_errors[errkind])
     -- TODO what to do if this fails?
     pcall(dispatchers.on_error, errkind, ...)
   end
-  --@private
+  ---@private
   local function pcall_handler(errkind, status, head, ...)
     if not status then
       on_error(errkind, head, ...)
@@ -477,7 +477,7 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
     end
     return status, head, ...
   end
-  --@private
+  ---@private
   local function try_call(errkind, fn, ...)
     return pcall_handler(errkind, pcall(fn, ...))
   end
@@ -486,7 +486,7 @@ local function start(cmd, cmd_args, dispatchers, extra_spawn_params)
   -- time and log them. This would require storing the timestamp. I could call
   -- them with an error then, perhaps.
 
-  --@private
+  ---@private
   local function handle_body(body)
     local decoded, err = json_decode(body)
     if not decoded then