Hammerspoon / Hammerspoon/Spoons
Documentation quality---usage examples?
- Dominant language
- Lua
- Stars
- 567
- Forks
- 171
- PR merge metrics
- No merged PRs in 30d
Description
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](https://github.com/Hammerspoon/Spoons/blob/0cf7087f93666b7054460e25426fa0f34bc39601/Source/RecursiveBinder.spoon/init.lua#L249) 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.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.