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.
This commit is contained in:
Gregory Anders
2021-08-22 14:55:28 -06:00
committed by GitHub
parent 649dbb3b15
commit c2a211b8e3
24 changed files with 689 additions and 687 deletions

View File

@@ -28,9 +28,9 @@ setmetatable(M, {
---
--- It is not recommended to use this, use vim.treesitter.get_parser() instead.
---
--- @param bufnr The buffer the parser will be tied to
--- @param lang The language of the parser
--- @param opts Options to pass to the created language tree
---@param bufnr The buffer the parser will be tied to
---@param lang The language of the parser
---@param opts Options to pass to the created language tree
function M._create_parser(bufnr, lang, opts)
language.require_language(lang)
if bufnr == 0 then
@@ -71,11 +71,11 @@ end
--- If needed this will create the parser.
--- Unconditionnally attach the provided callback
---
--- @param bufnr The buffer the parser should be tied to
--- @param lang The filetype of this parser
--- @param opts Options object to pass to the created language tree
---@param bufnr The buffer the parser should be tied to
---@param lang The filetype of this parser
---@param opts Options object to pass to the created language tree
---
--- @returns The parser
---@returns The parser
function M.get_parser(bufnr, lang, opts)
opts = opts or {}
@@ -97,9 +97,9 @@ end
--- Gets a string parser
---
--- @param str The string to parse
--- @param lang The language of this string
--- @param opts Options to pass to the created language tree
---@param str The string to parse
---@param lang The language of this string
---@param opts Options to pass to the created language tree
function M.get_string_parser(str, lang, opts)
vim.validate {
str = { str, 'string' },