Add LuaCATS as alternative tag handling scheme

[alerque]

trafficstars

Unfortunately documentation tagging systems have proliferated and fragmented. The current pretty de facto Lua Language Server (Sumneko) uses the LuaCATS annotation system which are derived from EmmyLua annotations which are derived from LDoc which is derived from LuaDoc. Of course LDoc eventually dropped cross-compatibility with LuaDoc, and EmmyLua eventually dropped cross-compatibility with LDoc, and LuaCATS dropped cross-compatibility with EmmyLua.

So :facepalm:

Having the LSP type hints working is rather handy in some editors, but it doesn't play nice with LDoc style comments. Unfortunately the docs generation features of Lua_LS or EmmyLua are pretty rudimentary compared to how LDoc can put things together. I'd rather be able to keep using ldoc instead of lua-language-server --doc while also getting LSP features.

I'm wondering it it wouldn't be possible to support all or most of the LuaCATS tag syntax without too much trouble. Already with custom tags I can get part of the way there, but it's obnoxious to do everything with custom parsers and try to disable the default features for overlapping tags like @param.

For example:

--- LDoc
-- @tparam string var A string type parameter.

--- LuaCATS
-- @param var string A string type parameter.

The issue is LuaCATS doesn't know and can't easily be taught how to handle @tparam and LDoc can't easily override @param to handle typing using a different option order than the default.