Fix some corrupt returns and params in the docs.

Apparently LuaCATS can't deal with `@return foo?` syntax ??
So use `|nil` explicitly.

And remove the @'s in front of some doctsrings, all these Lua tools fight with
each other on syntax, let's remember which is the one that wants these.

doc/lean.txt

@@ -27,7 +27,9 @@ lean.plugin_version()                                      *lean.plugin_version*
     Try to find what version of `lean.nvim` this is.
 
     Assumes your `lean.nvim` comes from a `git` repository.
-    @return string?
+
+    Returns: ~
+        (string|nil)  version
 
 
 lean.use_suggested_mappings({bufnr?})              *lean.use_suggested_mappings*
@@ -81,7 +83,7 @@ Pin                                                                        *Pin*
     An individual pin.
 
     Fields: ~
-        {id}  (string)  @a label to identify the pin
+        {id}  (string)  a label to identify the pin
 
 
 Info                                                                      *Info*
@@ -262,8 +264,10 @@ loogle.search({type})                                            *loogle.search*
 
     Parameters: ~
         {type}  (string)  The type pattern to look for.
-                          @return LoogleResult[]? results Loogle hits in the JSON API format
-                          @return string? err An error message from Loogle, in which case no results are returned
+
+    Returns: ~
+        (LoogleResult[]|nil)  Loogle hits in the JSON API format
+        (string|nil)          An error message from Loogle, in which case no results are returned
 
 
 loogle.template({result})                                      *loogle.template*
@@ -317,8 +321,11 @@ lsp.plain_goal({params}, {bufnr})                               *lsp.plain_goal*
 
     Parameters: ~
         {params}  (lsp.TextDocumentPositionParams)
-        {bufnr}   (number)                          @return LspError? error
-                                                    @return PlainGoal? plain_goal
+        {bufnr}   (number)
+
+    Returns: ~
+        (LspError|nil)   error
+        (PlainGoal|nil)  plain_goal
 
 
 PlainTermGoal                                                    *PlainTermGoal*
@@ -333,8 +340,11 @@ lsp.plain_term_goal({params}, {bufnr})                     *lsp.plain_term_goal*
 
     Parameters: ~
         {params}  (lsp.TextDocumentPositionParams)
-        {bufnr}   (number)                          @return LspError? error
-                                                    @return PlainTermGoal? plain_term_goal
+        {bufnr}   (number)
+
+    Returns: ~
+        (LspError|nil)       error
+        (PlainTermGoal|nil)  plain_term_goal
 
 
 LeanFileProgressParams                                  *LeanFileProgressParams*
@@ -371,7 +381,7 @@ stderr.show({message})                                             *stderr.show*
     Show stderr output in a separate stderr buffer.
 
     Parameters: ~
-        {message}  (string)  @a (possibly multi-line) string from stderr
+        {message}  (string)  a (possibly multi-line) string from stderr
 
 
 stderr.enable()                                                  *stderr.enable*

doc/tags

@@ -48,6 +48,7 @@ lean.init	lean.txt	/*lean.init*
 lean.loogle	lean.txt	/*lean.loogle*
 lean.lsp	lean.txt	/*lean.lsp*
 lean.nvim	lean.txt	/*lean.nvim*
+lean.plugin_version	lean.txt	/*lean.plugin_version*
 lean.satellite	lean.txt	/*lean.satellite*
 lean.setup	lean.txt	/*lean.setup*
 lean.sorry	lean.txt	/*lean.sorry*

lua/lean/_util.lua

@@ -36,13 +36,13 @@ function M.lean_lsp_diagnostics(opts, bufnr)
 end
 
 ---@class CreateBufParams
----@field name? string @the name of the new buffer
----@field options? table<string, any> @a table of buffer options
----@field listed? boolean @see :h nvim_create_buf (default true)
----@field scratch? boolean @see :h nvim_create_buf (default false)
+---@field name? string the name of the new buffer
+---@field options? table<string, any> a table of buffer options
+---@field listed? boolean see :h nvim_create_buf (default true)
+---@field scratch? boolean see :h nvim_create_buf (default false)
 
 ---Create a new buffer.
----@param params CreateBufParams @new buffer options
+---@param params CreateBufParams new buffer options
 ---@return integer: the new bufnr`
 function M.create_buf(params)
   if params.listed == nil then
@@ -165,7 +165,7 @@ end
 ---@field position { line: uinteger, character: uinteger }
 
 ---Check that the given position parameters are valid given the buffer they correspond to.
----@param params UIParams @parameters to verify
+---@param params UIParams parameters to verify
 ---@return boolean
 function M.position_params_valid(params)
   local bufnr = vim.uri_to_bufnr(params.textDocument.uri)

lua/lean/infoview.lua

@@ -61,7 +61,7 @@ options._DEFAULTS = vim.deepcopy(options)
 
 ---An individual pin.
 ---@class Pin
----@field id string @a label to identify the pin
+---@field id string a label to identify the pin
 ---@field private __data_element Element
 ---@field private __element Element
 ---@field private __extmark number
@@ -85,7 +85,7 @@ Pin.__index = Pin
 ---@field private __diff_pin Pin
 ---@field private __pins_element Element
 ---@field private __diff_pin_element Element
----@field private __infoview Infoview @the infoview this info is attached to
+---@field private __infoview Infoview the infoview this info is attached to
 ---@field private __win_event_disable boolean
 local Info = {}
 Info.__index = Info
@@ -342,8 +342,8 @@ function Infoview:select_view_options()
 end
 
 ---API for opening an auxilliary window relative to the current infoview window.
----@param buf number @buffer to put in the new window
----@return number? @new window handle or nil if the infoview is closed
+---@param buf number buffer to put in the new window
+---@return number? new window handle or nil if the infoview is closed
 function Infoview:__open_win(buf)
   if not self.window then
     return
@@ -406,7 +406,7 @@ function Infoview:__refresh()
 end
 
 ---Filter the pins from this infoview which are relevant to a given buffer.
----@param uri string @the URI which filters the pins
+---@param uri string the URI which filters the pins
 ---@return Pin[]
 function Infoview:pins_for(uri)
   if not self.window then
@@ -835,7 +835,7 @@ function Info:move_pin(params)
 end
 
 ---Toggle auto diff pin mode.
----@param clear boolean @clear the pin when disabling auto diff pin mode?
+---@param clear boolean clear the pin when disabling auto diff pin mode?
 function Info:__toggle_auto_diff_pin(clear)
   if self.__auto_diff_pin then
     self.__auto_diff_pin = false

lua/lean/infoview/components.lua

@@ -55,8 +55,8 @@ local function goal_header(goals)
 end
 
 ---The current (tactic) goal state.
----@param goal PlainGoal: a Lean `plainGoal` LSP response
----@return Element[]
+---@param goal PlainGoal a Lean `plainGoal` LSP response
+---@return Element[] goals the current plain goals
 function components.plain_goal(goal)
   if type(goal) ~= 'table' or not goal.goals then
     return {}
@@ -92,7 +92,7 @@ function components.plain_goal(goal)
 end
 
 ---The current (term) goal state.
----@param term_goal table: a Lean `plainTermGoal` LSP response
+---@param term_goal table a Lean `plainTermGoal` LSP response
 ---@return Element[]
 function components.term_goal(term_goal)
   if type(term_goal) ~= 'table' or not term_goal.goal then

lua/lean/init.lua

@@ -163,7 +163,7 @@ end
 ---Try to find what version of `lean.nvim` this is.
 ---
 ---Assumes your `lean.nvim` comes from a `git` repository.
----@return string?
+---@return string|nil version
 function lean.plugin_version()
   local result = util.subprocess_run {
     command = 'git',

lua/lean/loogle.lua

@@ -16,8 +16,8 @@ local loogle = {}
 
 ---Search Loogle for the given type.
 ---@param type string The type pattern to look for.
----@return LoogleResult[]? results Loogle hits in the JSON API format
----@return string? err An error message from Loogle, in which case no results are returned
+---@return LoogleResult[]|nil results Loogle hits in the JSON API format
+---@return string|nil err An error message from Loogle, in which case no results are returned
 function loogle.search(type)
   local res = curl.get {
     url = 'https://loogle.lean-lang.org/json',

lua/lean/lsp.lua

@@ -41,8 +41,8 @@ end
 ---Fetch goal state information from the server (async).
 ---@param params lsp.TextDocumentPositionParams
 ---@param bufnr number
----@return LspError? error
----@return PlainGoal? plain_goal
+---@return LspError|nil error
+---@return PlainGoal|nil plain_goal
 function lsp.plain_goal(params, bufnr)
   local client = lsp.client_for(bufnr)
   if not client then
@@ -63,8 +63,8 @@ end
 ---Fetch term goal state information from the server (async).
 ---@param params lsp.TextDocumentPositionParams
 ---@param bufnr number
----@return LspError? error
----@return PlainTermGoal? plain_term_goal
+---@return LspError|nil error
+---@return PlainTermGoal|nil plain_term_goal
 function lsp.plain_term_goal(params, bufnr)
   local client = lsp.client_for(bufnr)
   if not client then

lua/lean/stderr.lua

@@ -34,7 +34,7 @@ local function open_window(stderr_bufnr)
 end
 
 ---Show stderr output in a separate stderr buffer.
----@param message string @a (possibly multi-line) string from stderr
+---@param message string a (possibly multi-line) string from stderr
 function stderr.show(message)
   vim.schedule(function()
     if not current.bufnr or not vim.api.nvim_buf_is_valid(current.bufnr) then

lua/lean/tui.lua

@@ -35,14 +35,14 @@ local util = require 'lean._util'
 
 ---An individual console user interface element.
 ---@class Element
----@field events EventCallbacks @functions to fire for events which this element responds to
----@field text string @the text to show when rendering this element
----@field name string @a named handle for this element, used when path-searching
----@field hlgroup? string|fun(string):string @the highlight group for this element's text, or a function that returns it
+---@field events EventCallbacks functions to fire for events which this element responds to
+---@field text string the text to show when rendering this element
+---@field name string a named handle for this element, used when path-searching
+---@field hlgroup? string|fun(string):string the highlight group for this element's text, or a function that returns it
 ---@field tooltip? Element? tooltip
----@field highlightable boolean @(for buffer rendering) whether to highlight this element when hovering over it
+---@field highlightable boolean (for buffer rendering) whether to highlight this element when hovering over it
 ---@field _size? integer Computed size of this element, updated by `Element:to_string`
----@field private __children Element[] @this element's children
+---@field private __children Element[] this element's children
 local Element = {}
 Element.__index = Element
 
@@ -66,12 +66,12 @@ local BufRenderer = {
 BufRenderer.__index = BufRenderer
 
 ---@class ElementNewArgs
----@field events? EventCallbacks @event function map
----@field text? string @the text to show when rendering this element
----@field name? string @a named handle for this element, used when path-searching
----@field hlgroup? string|fun():string @the highlight group for this element's text, or a function that returns it
----@field highlightable boolean? @(for buffer rendering) whether to highlight this element when hovering over it
----@field children? Element[] @this element's children
+---@field events? EventCallbacks event function map
+---@field text? string the text to show when rendering this element
+---@field name? string a named handle for this element, used when path-searching
+---@field hlgroup? string|fun():string the highlight group for this element's text, or a function that returns it
+---@field highlightable boolean? (for buffer rendering) whether to highlight this element when hovering over it
+---@field children? Element[] this element's children
 
 ---Create a new Element.
 ---@param args? ElementNewArgs
@@ -109,15 +109,15 @@ function Element:set_children(children)
 end
 
 ---Add a child to this element.
----@param child Element @child element to add
+---@param child Element child element to add
 ---@return nil
 function Element:add_child(child)
   table.insert(self.__children, child)
 end
 
 ---Set this element's tooltip.
----@param element Element @element to use as a tooltip for this element
----@return Element @the added tooltip element
+---@param element Element element to use as a tooltip for this element
+---@return Element the added tooltip element
 function Element:add_tooltip(element)
   self.tooltip = element
   return element
@@ -191,14 +191,14 @@ end
 
 ---Represents a node in a path through an element.
 ---@class PathNode
----@field idx number @the index in the current element's children to follow
----@field name string @the name that the indexed child should have
----@field offset number? @if provided, a byte offset from the beginning of this element
+---@field idx number the index in the current element's children to follow
+---@field name string the name that the indexed child should have
+---@field offset number? if provided, a byte offset from the beginning of this element
 
 ---Get the raw byte position of the element arrived at by following the given path.
----@param path PathNode[] @the path to follow
----@return number? @the position if the path was valid, nil otherwise
----@return number? @the additional byte offset from the position if the path was valid, nil otherwise
+---@param path PathNode[] the path to follow
+---@return number? the position if the path was valid, nil otherwise
+---@return number? the additional byte offset from the position if the path was valid, nil otherwise
 function Element:pos_from_path(path)
   local pos = 1
   for i, p in ipairs(path) do
@@ -225,9 +225,9 @@ function Element:pos_from_path(path)
 end
 
 ---Get the element stack and element arrived at by following the given path.
----@param path PathNode[] @the path to follow
----@return Element[]? @the stack of elements at this path, or nil if the path is invalid
----@return Element? @the element at this path, or nil if the path is invalid
+---@param path PathNode[] the path to follow
+---@return Element[]? the stack of elements at this path, or nil if the path is invalid
+---@return Element? the element at this path, or nil if the path is invalid
 function Element:div_from_path(path)
   local stack = { self }
   for i, p in ipairs(path) do
@@ -345,8 +345,8 @@ function Element:path_from_pos(pos)
 end
 
 ---Trigger the given event at the given path
----@param path PathNode[] @the path to trigger the event at
----@param event ElementEvent @the event to fire
+---@param path PathNode[] the path to trigger the event at
+---@param event ElementEvent the event to fire
 function Element:event(path, event, ...)
   local event_element = self:find_innermost_along(path, function(element)
     return element.events and element.events[event]
@@ -573,8 +573,8 @@ function BufRenderer:update_cursor(win)
 end
 
 ---Checks if two paths are equal, ignoring auxillary metadata (e.g. offsets)
----@param path_a PathNode[]? @first path
----@param path_b PathNode[]? @second path
+---@param path_a PathNode[]? first path
+---@param path_b PathNode[]? second path
 local function path_equal(path_a, path_b)
   if path_a == nil and path_b == nil then
     return true

spec/helpers.lua

@@ -59,8 +59,8 @@ function helpers.move_cursor(opts)
 end
 
 ---@class MoveCursorOpts
----@field window? integer @the window handle. Defaults to the current window.
----@field to table @the new cursor position (1-row indexed, as per nvim_win_set_cursor)
+---@field window? integer the window handle. Defaults to the current window.
+---@field to table the new cursor position (1-row indexed, as per nvim_win_set_cursor)
 
 ---Wait for all of the pins associated with the given infoview to finish loading/processing.
 ---@param iv? Infoview