Merge pull request #2762 from latenitefilms/patch-22

Updated hs.hotkey.bind() documentation to match hs.hotkey.new()

extensions/hotkey/init.lua

@@ -382,9 +382,10 @@ function hotkey.showHotkeys(mods,key)
   helpHotkey = hotkey.bind(mods,key,'Show active hotkeys',showHelp,alert.closeAll)
   return helpHotkey
 end
---- hs.hotkey.bind(mods, key, message, pressedfn, releasedfn, repeatfn) -> hs.hotkey object
+
+--- hs.hotkey.bind(mods, key, [message,] pressedfn, releasedfn, repeatfn) -> hs.hotkey object
 --- Constructor
---- Creates a hotkey and enables it immediately
+--- Creates a new hotkey and enables it immediately
 ---
 --- Parameters:
 ---  * mods - A table or a string containing (as elements, or as substrings with any separator) the keyboard modifiers required,
@@ -394,16 +395,23 @@ end
 ---    * "alt", "option" or "⌥"
 ---    * "shift" or "⇧"
 ---  * key - A string containing the name of a keyboard key (as found in [hs.keycodes.map](hs.keycodes.html#map) ), or a raw keycode number
----  * message - A string containing a message to be displayed via `hs.alert()` when the hotkey has been triggered, or nil for no alert
+---  * message - (optional) A string containing a message to be displayed via `hs.alert()` when the hotkey has been
+---    triggered; if omitted, no alert will be shown
 ---  * pressedfn - A function that will be called when the hotkey has been pressed, or nil
 ---  * releasedfn - A function that will be called when the hotkey has been released, or nil
 ---  * repeatfn - A function that will be called when a pressed hotkey is repeating, or nil
 ---
 --- Returns:
----  * A new `hs.hotkey` object for method chaining
+---  * A new `hs.hotkey` object or nil if the hotkey could not be enabled
 ---
 --- Notes:
 ---  * This function is just a wrapper that performs `hs.hotkey.new(...):enable()`
+---  * You can create multiple `hs.hotkey` objects for the same keyboard combination, but only one can be active
+---    at any given time - see `hs.hotkey:enable()`
+---  * If `message` is the empty string `""`, the alert will just show the triggered keyboard combination
+---  * If you don't want any alert, you must *actually* omit the `message` parameter; a `nil` in 3rd position
+---    will be interpreted as a missing `pressedfn`
+---  * You must pass at least one of `pressedfn`, `releasedfn` or `repeatfn`; to delete a hotkey, use `hs.hotkey:delete()`
 function hotkey.bind(...)
   return hotkey.new(...):enable()
 end