documentation scheme

[tehn]

it occurred to me that we should consider a documentation scheme. perhaps once we identify a format or tool, i should write it up and then you can clarify/correct? basically need to document the timer functions, monome functions, engine parameters, etc.

something lightweight would be best. not sure if it's preferable to use something that lives inside the code itself.

[catfact]

i think you are talking about documenting the lua API that is defined in C (with calls to lua_register.) agreed, this is important to do. i've even poked at source code for some games with lua APIs to see how its done in the wild. doesn't seem to be a consistent approach (surprised luadocs doesn't have some feature for this.)

two ideas:

• keep all calls to lua_register in a single source file. scrape this and produce api.lua or something on build. use luadoc to produce html or whatever, if you want that.

• some people wrap their lua api in a c/c++ api and use doxygen, with some customized doxyfile to deal with the api wrapper source in a specifc way. to me this only makes sense if you love doxygen anyway (which i don't)

[tehn]

i have no preference for doxygen.

i can check out how sam did it with teletype, but i have a feeling it's a very heavy approach using pydoc etc.

On Wed, Oct 25, 2017 at 12:54 AM, ezra buchla notifications@github.com wrote:

i think you are talking about documenting the lua API that is defined in C (with calls to lua_register.) agreed, this is important to do. i've even poked at source code for some games with lua APIs to see how its done in the wild. doesn't seem to be a consistent approach (surprised luadocs doesn't have some feature for this.)

two ideas:

-

keep all calls to lua_register in a single source file. scrape this and produce api.lua or something on build. use luadoc to produce html or whatever, if you want that.

some people wrap their lua api in a c/c++ api and use doxygen, with some customized doxyfile to deal with the api wrapper source in a specifc way. to me this only makes sense if you love doxygen anyway (which i don't)

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/catfact/norns/issues/29#issuecomment-339214098, or mute the thread https://github.com/notifications/unsubscribe-auth/AAPEcOQVsd2oYzuWpGrKdA262khP6oJsks5svr8JgaJpZM4MkS7o .

[catfact]

ok, we probably want to just use luadoc then, its easy and simple

contrary to my earlier statement, luadoc can parse c files with appropriate tag comments. https://stevedonovan.github.io/ldoc/manual/doc.md.html

[tehn]

excellent. scanning the link now.

[tehn]

made progress. have a config.ld and make docs now.

organization is tricky, however. i've ldoc'd weaver.c which is really the only relevant file for lua-specific interaction, but calling weaver its own module makes no sense, as the functionality is spread between screen, grid, etc. i fiddled with ldoc submodules which i couldn't get to work elegantly.

but perhaps this actually doesn't matter-- and that weaver shouldn't be documented directly. for example, with the screen, i'll be making a sort of gatekeeper system-- where the functions are redefined based on being in system/menu mode or "app" mode.

the idea is that when in system mode, the screen/encs/keys are all controlled by the system menu script (for loading/etc). on exit, the screen/encs/keys are released to the user script.

so the actual weaver calls are a bit behind the scenes. for example:

function screen_line(x,y) is the user-accessible draw. when in user-script mode this points to s_line() (perhaps i should rename the weaver functions so they're more obviously lua-c glue). but when system mode is entered (by touching key 1) screen_line gets directed to a null function, and the system script redraws the screen however with direct calls to s_line(). upon exiting system mode the screen_line functions are restored, and some sort of user redraw function is called (which should be redefined by each user script).

the point of all of this: i can make a file, screen.lua, that has these user-script functions like screen_line and do the ldoc there, instead of in weaver.c. this way the modules all stay organized together. of course this introduces fragility (ie, if weaver is changed by the docs aren't) but it might make the whole system more readable.

now of course, there are probably functions in weaver that don't need to be blocked/redefined in system mode, ie time since epoch.

i'm going to reopen this until it's figured out.

[tehn]

screen functions documented in screen.lua

https://github.com/catfact/norns/pull/196