ldoc
ldoc copied to clipboard
lunarmodules
LDoc can't handle non-alphanums in @fields and @function names
LDoc can't handle non-alphanums in @fields, here:
http://rrthomas.github.io/lua-stdlib/modules/std.functional.html#op
Notice all the actual field names are missing, compared to:
https://github.com/rrthomas/lua-stdlib/blob/master/ext/std/functional.lua#L176
I would also have liked to document metamethods according to their operator, e.g in std.set, rather than:
-- @metamethod __add
IMHO, more readable would be:
-- @metamethod +
I created a custom @metamethod keyword in config.ld with:
new_type("metamethod", "Metamethods", false, "params")
However, that suffers from the same problem as Issue 2, above. Curiously, it does work sometimes:
-- @metamethod ..
for __concat does work as expected, but I didn't use it yet because most of the others are ignored.
Thinking about this some more, documenting infix operators with std.string:.. is even worse than std.string:__concat, and not all metamethods even translate to an infix operator (__tostring, __index, __call, etc), so short of designing a new syntax for documenting pre/post/in-fix operators, I think the @metamethod thing is a red herring.
That said, I'd still like to be able to document non-alphanum table @fields, so that I can generate the ops table documentation properly.
I feel your pain, but don't know if it's worth the trouble at the moment. The implementation would be tricky, and the feature would have consequences. Maybe after we have a nice solid 1.4.2 we can reconsider?
Sure. I guessed it might be more involved that fixing a regexp, since I couldn't find said regexp after a moderately thorough search of the sources.
1.4.2?!? Is the 1.4.0 zip ball at github an official release? If so, can you submit it to LuaRocks (which still has 1.3.12 as the newest available release)? Or, I can tweak the rockspec and submit for you if you are too busy.
That way, I can have a non-moving target for a @classmod capable LDoc to aim at with my client projects, rather than jumping through hoops to get a matching git revision into TravisCI so that my projects don't always show up as 'failing' :)
On Wed, Jan 8, 2014 at 5:22 AM, Gary V. Vaughan [email protected]:
1.4.2?!? Is the 1.4.0 zip ball at github an official release? If so, can you submit it to LuaRocks (which still has 1.3.12 as the newest available release)? Or, I can tweak the rockspec and submit for you if you are too busy.
Brilliant idea - was holding off before submitting, but I think master is looking good. The rockspec in the repo was patched by Hisham and should work fine. Let's look at any show-stoppers and go for a rockspec release - which anyway is a good idea to get more people testing it.
Awesome :)
I don't think there are any real show stoppers now either... the only thing that is any issue at all are the various open sidebar issues, but those are purely cosmetic, and master is considerably more featureful than 1.3.12 by any measure!
As far as I can tell this is still not implemented. The current metamethod docs in lua-stdlib seem pretty understandable to me (e.g. std.sed metamethods).
Contributions welcome. I don't have a lot of time to develop this myself but am trying to keep up with facilitating PRs.
