Documentation quality---usage examples?

[paultopia]

Hi there,

Can we (and I say we because I'm happy to work on this in part myself if there's support) work on improving documentation quality for the spoons in this respository? Right now some seem to be essentially undocumented.

One that I'm trying to figure out how to use right now, for example, is RecursiveBinder. If I'm reading the general description right, that spoon should allow one to define nested modal keybindings. But the documentation for that spoon is incoherent in places. For example, describing the one argument to the RecursiveBinder.recursiveBind(keymap) method:

Note: Spec of keymap: Every key is of format {{modifers}, key, (optional) description} The first two element is what you usually pass into a hs.hotkey.bind() function.

Each value of key can be in two form:

A function. Then pressing the key invokes the function
A table. Then pressing the key bring to another layer of keybindings. And the table have the same format of top table: keys to keys, value to table or function

The problem is that this is incoherent. The first option for what the key can be suggests that the key element of a keymap is both a key, i.e., the thing you press on the keyboard, like in normal hammerspoon keybindings, and the function or table which it invokes. In other words, how can the value of key be a function, such that pressing the key designated by key invokes the function also designated by key???

Looking at the comments in the source suggests that it's possible to just pass a function in place of the whole keymap, though if one does so, it's a mystery how one specifies which keybinding goes with this function...

Anyway, the point is that it's impossible to figure out how to use this even to the "hello world" level except by, I guess, walking through the internals of the entire spoon oneself. A simple usage example that just defined a hello world function and showed how to bind it would massively clear things up.

[latenitefilms]

Absolutely! Feel free to do a pull request with any documentation improvements. You could also add an example usage in the main top level documentation?

[cmsj]

Agreed, I'm very happy to take PRs that improve docs.

One note - please change the docs in the .lua files only - the json/html are automatically generated when Pull Requests are merged.