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

diff --git a/runtime/lua/vim/uri.lua b/runtime/lua/vim/uri.lua
index 82c9a31464..a3e79a0f2b 100644
--- a/runtime/lua/vim/uri.lua
+++ b/runtime/lua/vim/uri.lua
@@ -9,7 +9,7 @@ do
   local schar = string.char
 
   --- Convert hex to char
-  --@private
+  ---@private
   local function hex_to_char(hex)
     return schar(tonumber(hex, 16))
   end
@@ -38,7 +38,7 @@ do
     tohex = function(b) return string.format("%02x", b) end
   end
 
-  --@private
+  ---@private
   local function percent_encode_char(char)
     return "%"..tohex(sbyte(char), 2)
   end
@@ -50,14 +50,14 @@ do
 end
 
 
---@private
+---@private
 local function is_windows_file_uri(uri)
   return uri:match('^file:/+[a-zA-Z]:') ~= nil
 end
 
 --- Get a URI from a file path.
---@param path (string): Path to file
---@return URI
+---@param path (string): Path to file
+---@return URI
 local function uri_from_fname(path)
   local volume_path, fname = path:match("^([a-zA-Z]:)(.*)")
   local is_windows = volume_path ~= nil
@@ -77,8 +77,8 @@ end
 local URI_SCHEME_PATTERN = '^([a-zA-Z]+[a-zA-Z0-9+-.]*):.*'
 
 --- Get a URI from a bufnr
---@param bufnr (number): Buffer number
---@return URI
+---@param bufnr (number): Buffer number
+---@return URI
 local function uri_from_bufnr(bufnr)
   local fname = vim.api.nvim_buf_get_name(bufnr)
   local scheme = fname:match(URI_SCHEME_PATTERN)
@@ -90,8 +90,8 @@ local function uri_from_bufnr(bufnr)
 end
 
 --- Get a filename from a URI
---@param uri (string): The URI
---@return Filename
+---@param uri (string): The URI
+---@return Filename
 local function uri_to_fname(uri)
   local scheme = assert(uri:match(URI_SCHEME_PATTERN), 'URI must contain a scheme: ' .. uri)
   if scheme ~= 'file' then
@@ -109,9 +109,9 @@ local function uri_to_fname(uri)
 end
 
 --- Return or create a buffer for a uri.
---@param uri (string): The URI
---@return bufnr.
---@note Creates buffer but does not load it
+---@param uri (string): The URI
+---@return bufnr.
+---@note Creates buffer but does not load it
 local function uri_to_bufnr(uri)
   local scheme = assert(uri:match(URI_SCHEME_PATTERN), 'URI must contain a scheme: ' .. uri)
   if scheme == 'file' then