fix ldoc comments for classes

[catfact]

we're using @module when we apparently should be using @classmod for classes.

this will correctly differentiate in the output between methods (with colon and self) and static functions (with dot.)

also, a lot of class/module files are totally missing ldoc comments:

> ldoc .
/home/emb/norns/lua/core/clock.lua:69: no module() call found; no initial doc comment
/home/emb/norns/lua/core/hid_events.lua:752: no module() call found; no initial doc comment
/home/emb/norns/lua/core/mix.lua:167: no module() call found; no initial doc comment
/home/emb/norns/lua/core/vport.lua:28: no module() call found; no initial doc comment
/home/emb/norns/lua/core/wifi.lua:341: no module() call found; no initial doc comment
/home/emb/norns/lua/lib/beatclock.lua:160: no module() call found; no initial doc comment
/home/emb/norns/lua/lib/er.lua:25: no module() call found; no initial doc comment
/home/emb/norns/lua/lib/formatters.lua:172: no module() call found; no initial doc comment
/home/emb/norns/lua/lib/gridbuf.lua:99: no module() call found; no initial doc comment
/home/emb/norns/lua/lib/pattern_time.lua:107: no module() call found; no initial doc comment

fixing this should be easy, if slightly tedious

[catfact]

actually i still don't really get it.

if i just change @module to @classmod at the top of midi.lua, ldoc interprets all functions in the Midi table as "methods," (displays them with a colon) - even the static functions like Midi.new, etc.

if i leave @module at the top, and add @classmod later (above the method declarations) then they all show up as class functions (with a dot.)

it seems to be all or nothing. but there's gotta be a way.

[ypxk]

the ldoc thing has bothered me before. i don’t know that i will get a big enough chunk of spare time to figure out all the steps in submitting a pull request for fixing it, but i am going to try to do it by next week and will report back if i fail.

edit: update, this is definitely not going to happen from me, basically immediately after posting that Day Job set an extremely ambitious deadline.... someday.

[okyeron]

The Sections part of the ldoc docs mentions the @type section

A specialized kind of section is type: it is used for documenting classes. The functions (or fields) within a type section are considered to be the methods of that class.

Does that help in this situation?

[scazan]

I was trying to find out what the arguments for controlspec were and noticed it was undocumented, so I went and did the ldoc comments for the file using @classmod after finding this thread. I do notice that controlspec ends up separately under Classes rather than Modules so I'm thinking maybe if the docs are going with @classmod it should all be done together.

I used @section to specify the predefined controlspecs and that works pretty well. It did differentiate that way. Perhaps @section could be used for static methods as well.

You can see that here: https://github.com/scazan/norns/blob/controlspec-ldoc/lua/core/controlspec.lua

Happy to do some documentation updating for this. Alternatively, until that is done should I stick with @module?

Screenshot of @section rendering attached:

[scazan]

I think that #971 "mostly" closes the classmod issue here. Still some undocumented classes perhaps. I made use of the @static tag which seems to be an undocumented feature of ldoc.

[catfact]

lets close for now, feel free to reopen if egregious omissions are noticed