scrub API docs

[tehn]

the inline luadocs for all of the lua files need a serious scrubbing.

[jasonw22]

Can I see a "before" and "after" example?

[okyeron]

For my own reference: https://github.com/stevedonovan/LDoc

Is there a way to hack ldoc to add an exclude or omit tag for individual functions? (rather than excluding whole files with exclude in config.ld).

Perhaps no - I'm not finding anything like that in my quick search of the ldoc docs.

[pq]

@okyeron: can you give me some examples of functions you'd want to exclude?

[okyeron]

Not sure I have one specifically. But @tehn mentioned this:

there are various irrelevant bits (ie, internal stuff like menu) and then some internal functions (also irrelevant to users, ie metro.new).

[okyeron]

Is there an example of a decent "scrubbed" lua doc that I could use as a reference to cleaning other files?

[okyeron]

I made a quick first pass at grid.lua and midi.lua here: https://github.com/okyeron/norns/tree/ldoc-cleanup

[pq]

@okyeron: those changes look like a good improvement. maybe open a PR against dev?

as for examples, maybe @tehn has some?

in general, we should definitely agree on some guidelines.

the lua rocks advice on documenting types in param descriptions is good I think. otherwise, I expect we could adapt advice from a better documented language to lua (since I'm not seeing anything specific). we put together an Effective Dart section on docs for dart. i'd be happy to port them over as a jumping-off point if there's interest. at a philosophical level, i agree with what we've captured for flutter --- my other day job --- so i'd be inclined to consider folding some of that advice in.

anyway, let me know what you all think!

[okyeron]

forgot to put a reference in this thread

725

[okyeron]

@tehn mentioned this over on another thread: ldoc can be run from the norns directory if you've installed the right goodies.

Doing so shows a bunch of stuff that might need to be omitted:

• core.menu
• engines: MollyThePoly, Passersby
• user.lib.ansible.kria
• user.lib.textentry

Stuff that has no documentation:

• Controlspec
• file (i'm not sure where this is coming from - fileselect.lua? )
• softcut

Query - will sort in config.ld sort the Modules list alphabetically?

[okyeron]

What is sceen.font_face(0)? The inline docs for screen start the font list at index 1

[tehn]

where do you see a reference to font_face(0)? it's likely an error. i'd have to check weaver/oracle to see how out-of-range is handled

[okyeron]

References: all over the place: https://github.com/monome/norns/blob/470031df3ab98c18cf3baa9318a1a60a8756b97e/lua/core/menu.lua#L190 https://github.com/monome/norns/blob/1d1b4a669a04c3a79f0748034b47d8418b1e16e1/lua/fileselect.lua#L117 https://github.com/monome/norns/blob/51590be3b595e0020d54b0be109c3826ac1e4bdf/lua/script.lua#L60

FWIW font_face(0) is not out of range if I use it in a script - and it also shows a different font than anything 1-14

[okyeron]

Should wifi functions be added to api docs?

not sure how to add this exactly, but I would find it handy to know what's in the wifi table

  wifi.status
  wifi.state
  wifi.ip
  wifi.signal
  wifi.connection_name

[okyeron]

FWIW - I updated metro.init() but it still doesn't look quite right. What do I need to fix here:

--- initialize a metro.
-- assigns unused id.
-- @param arg callback function
-- @param arg_time time period between ticks (seconds).
-- @param arg_count number of ticks. infinite by default.
function Metro.init(arg, arg_time, arg_count)
  local event = 0
  local time = arg_time or 1
  local count = arg_count or -1

[tehn]

fixed font_face in https://github.com/monome/norns/pull/730

wifi doesn't need to be doc'd yet. it's fundamentally system logic. i'm trying to focus on user-script related libs.

re: metro, looks fine to me. arg can also be a table (see 2.0 syntax doc)

[tehn]

also pushed docs for softcut

[okyeron]

Yay! Except that I have a typo on the arc docs. DOH!

[okyeron]

Quick thought - will the docs at https://monome.github.io/norns/doc/ be automatically updated with 2.0 release, or is that a task that should be added to a checklist somewhere?

[tehn]

those are auto exported from the master branch on change, thanks to @pq

[okyeron]

Checking in on docs (as it looks like the beta has stabilized a bit).

Is there something I can do to flag sections of ldoc to get ignored? I don't see anything in the config.ld spec that let's you skip/ignore files.

And then - which items should be ignored? Anything with a blank page for now?

[okyeron]

Checking in here - I've got some free time and could spend time this weekend tweaking docs.

Are there any specific areas that need lotsa help before release next week?

[tehn]

@okyeron i think we're in a pretty good place for the API docs.

would appreciate any further testing of the beta ahead of launch!