Feature request: Support for LuaCATS annotations

[Mange]

I'm trying my best to auto-generate documentation for my own project that uses LuaCATS, through Lua LSP to give me a good experience inside of my editor. I would like to be able to also publish documentation on the web, so I'm trying to integrate luadox.

Right now it works fairly well, but I get a lot of warnings because of unsupported annotations. I also need to duplicate all @param and convert them to the luadox @tparam, but the duplicated @param still emits a warning forever.

For example:

--- Rounds a number to the nearest integer.
---
--- @param n number The number to round.
--- @tparam number n The number to round.
function math.round(n)
  if n >= 0 then return math.floor(n + 0.5) end
  return math.ceil(n - 0.5)
end

I think it would be great to support the LuaCATS annotations in addition to our own ones.

Some suggestions

1. @param <name> <type> <description> as an alternative to @tparam <type> <name> <description>.
2. @return <type> [<name> [comment]] as an alternative to @treturn <type> [comment].
3. Supporting Markdown links a-la Returns a [MyThing](lua://MyThing) as an alternative to Returns a @{MyThing}.

[jtackaberry]

I actually started work along these lines a while back (in ee8f640 plus a bunch of uncommitted code), but got pulled in another direction and couldn't finish. I definitely understand the use case, and intend to better support LuaCATS too, by providing a LuaCATS mode for LuaDox, and the ability to explicitly namespace Luadox-specific annotations, e.g. @luadox:section.

I anticipate work will resume in a month or two, because I want to overhaul one of my larger Lua projects with LuaCATS annotations because I can't deal with not having LSP support anymore. :)

[SirWrexes]

Hi, sorry to bug you, any news on this matter ?
I've started developping some Lua tooling and it contains hundreds of lines LuaCATS annotations.
I'm trying to get some docs generated and all tools I've tried proved to be either quite unsatisfactory or just absurdly complex for no good reason.
This project looks like an almost perfect solution but I'm not a fan of having to rewrite the entirety of my docs plus doubling the annotations—I just know I'm going to forget and/or mess up something. 😅