create a lua api doc style guide

[pq]

follow-up from #455 and #725, we should hammer out lua api doc style guidelines.

a few points of reference:

• https://github.com/luarocks/lua-style-guide#documentation
• ldoc docs and examples: four.lua and multiple.lua

other language guidelines for inspiration:

• python: stackoverflow:standard-python-docstring-format @simonvanderveldt
• dart: dart doc style guidelines and flutter doc philosophy @pq

/cc @okyeron @jasonw22

[simonvanderveldt]

This example from ldoc might also be relevant for the alternative format https://stevedonovan.github.io/ldoc/examples/colon.lua.html

[okyeron]

Previous norns docs included a semicolon after the first line of text - I assume to indicate the text continues. I don't see that in the various ldoc examples. Example from grid.lua

--- static callback when any grid device is added;
-- user scripts can redefine

My assumption this should change to a period at the end of the first line and then at the end of sentences of description text?

[simonvanderveldt]

Doesn't seem like there are any requirements regarding if/what to use to signify end of a sentence in ldoc, so no need for semicolon. Can just use regular interpunction I guess?

[tehn]

FYI all, ldoc installation at the bottom of https://github.com/monome/norns/blob/master/readme-setup.md if you want to see the output of changes.

re: syntax, i prefer the simplest use (as shown at the top of the ldoc readme):

--- Summary ends with a period.
-- Some description, can be over several lines.
-- @param p1 first parameter
-- @param p2 second parameter
-- @return a string value

the period seems necessary?

simple @param without types seems adequate for our needs. i'd be good to add a colon after the name for clarity. ie @param varname: what is this var for

compact is good. less whitespace.

of course these are all just unqualified personal preferences.

[simonvanderveldt]

the period seems necessary?

All doc comments start with a summary sentence, that ends with a period or a question mark. An optional description may follow. Normally the summary sentence will appear in the module contents.

Seems like you're right :)

simple @param without types seems adequate for our needs. i'd be good to add a colon after the name for clarity. ie @param varname: what is this var for

Common tags are the ‘param’ tag which takes a parameter name followed by a parameter description separated by a space, and the ‘return’ tag which is simply followed by a description for a return value:

We should try if the colon works, the docs say the description should be separated by a space, which might mean it'll include the colon in the param's name.

[okyeron]

Running ldoc . on device will throw errors for syntax and stuff so this is kinda great for finding things to fix. :)

note - use tparam if specifying a type

If you want to specify a type for a parameter or a return value, there are also ‘tparam’ and ‘treturn’:

syntax for tparam and type should be:

-- @tparam type param_name : value The colon works OK, but must be separated by a space or it'll throw an param and formal argument name mismatch error.

[tehn]

yes, the agreed format for params is:

-- @tparam type param_name : value

close to figuring out a custom tag for user vs. system functions. @simonvanderveldt @pq