[mini.doc] Add support for ---@module annotations

[ColinKennedy]

Contributing guidelines

• I have read CONTRIBUTING.md
• I have read CODE_OF_CONDUCT.md

Module(s)

mini.doc

Description

LuaCATS Annotations supports a ---@module syntax. I believe that if this annotation is defined, a valid function namespace should have this module included in the generated output.

For example:

Given an input file like

---@module 'my_module'

local M = {}

--- Do something.
---@param value string Some text.
---@return number? # A value.
function M.to_number(value)
    return tonumber(value)
end

return M

Currently the output is:

==============================================================================
------------------------------------------------------------------------------
'my_module'

------------------------------------------------------------------------------
                                                                 *M.to_number()*
                             `M.to_number`({value})
Do something.
Parameters ~
{value} `(string)` Some text.
Return ~
`(number)` A value.


 vim:tw=78:ts=8:noet:ft=help:norl:

I think it would be better if the output instead would be

==============================================================================
------------------------------------------------------------------------------
'my_module'

------------------------------------------------------------------------------
                                                         *my_module.to_number()*
                             `to_number`({value})
Do something.
Parameters ~
{value} `(string)` Some text.
Return ~
`(number)` A value.


 vim:tw=78:ts=8:noet:ft=help:norl:

(Note the incorrect 'my_module' at the top. That's a separate bug that isn't related to this feature request)

Extra Considersations

Multiple Namespaces

It's possible to have multiple namespaces in Lua. The documentation generation should take care not to confuse them. For example

---@module 'my_module'

local M = {}
local H = {}

--- Do something.
---@param value string Some text.
---@return number? # A value.
function M.to_number(value)
    return H.to_number2(value)
end

--- Do something.
---@param value string Some text.
---@return number? # A value.
function H.to_number2(value)
    return tonumber(value)
end

return M

Would generate

==============================================================================
------------------------------------------------------------------------------
'my_module'

------------------------------------------------------------------------------
                                                         *my_module.to_number()*
                             `to_number`({value})
Do something.
Parameters ~
{value} `(string)` Some text.
Return ~
`(number)` A value.

------------------------------------------------------------------------------
                                                                *H.to_number2()*
                            `H.to_number2`({value})
Do something.
Parameters ~
{value} `(string)` Some text.
Return ~
`(number)` A value.


 vim:tw=78:ts=8:noet:ft=help:norl:

Because only M is returned.

Non-Standard Returns

Though uncommon, Lua lets you return you return non-tables. e.g. return "arbitrary thing here". I don't think a docstring autogenerator needs to handle a case like that other than to ignore it.

Table-Returns

More common sometimes people will return a module using a table like this:

---@module 'my_module'

return {
    --- Do something.
    ---@param value string Some text.
    ---@return number? # A value.
    to_number3 = function(value)
        return tonumber(value)
    end
}

Though that'd be cool to support too, I'd put that syntax in "nice to have" or a future addition.

[echasnovski]

Thanks for the suggestion!

I think having ---@module act as to replace the returned variable makes sense.

Also, as this seems to be a new-ish LuaCATS adoption and not EmmyLua-style (which 'mini.doc' is based on, yet doesn't claim to have full compatibility), I think it is reasonable to be tracked in a #666. So I'll close this and move/mention the suggestion there.