ldoc
ldoc copied to clipboard
lunarmodules
[Suggestion] Allow @type without methods
I'm working on documentation for luabnet_tools and I'm trying to document a Proxy type that doesn't have any methods.
Currently LDoc doesn't output anything about this type because it doesn't have any methods associated with it.
This is the current doc comment for the Proxy type:
--- A read-only proxy pointing to a decoded JSON result table.
-- Proxies are regular empty tables with their __index, __pairs and __ipairs metamethods pointing to the decoded result table.
-- Access to a subtable of the result table will return a Proxy pointing to the subtable. Non-table values are returned as normal.
-- Attempting to change the value of a Proxy's key will throw an error.
-- @type Proxy
Would it be possible to add support for empty types like this? If this is already possible, feel free to close this issue.
If you didn't want to change the way empty sections/types are output by default, it would be nice to have an @empty tag or an [empty] modifier of the @type tag to explicitly mark a type/section as empty.
My first thought was "Why not just use @table?". But that doesn't get labelled as a class, unfortunately. And empty @type items don't show because they don't have any contents. So yes, we would need a way to indicate 'empty' which would add a dummy item and then close the type (since it's really a section). Then have a convention for items which don't show up at all. Feels a little bit like a hack, but heaven knows we have enough of those already - why stop when we're enjoying ourselves?
I am having the same issue with a "class" with four methods (called Stream:new, Stream:reset, Stream:nextval, Stream:rep) that has some "derived classes". I would like to explain this derived classes (FuncStream, ListStream...) without having to show the same four methods but only with a description of this derived class.
It's been a while, did you ever make a decision regarding whether or not to add this functionality?
Contributions welcome. I don't have a lot of time to develop this myself but am trying to keep up with facilitating PRs.
