diff --git a/docs/capi/key.lua.in b/docs/capi/key.lua.in
index 4575aca5..6cd52e04 100644
--- a/docs/capi/key.lua.in
+++ b/docs/capi/key.lua.in
@@ -6,33 +6,34 @@
 
 --- Key object.
 --
--- @field key The key to press to triggers an event.
--- @field keysym Same as key, but return the name of the key symbol. It can
---   be identical to key, but for characters like '.' it will return 'period'.
--- @field modifiers The modifier key that should be pressed while the key is
---   pressed. An array with all the modifiers. Valid modifiers are: Any, Mod1,
---   Mod2, Mod3, Mod4, Mod5, Shift, Lock and Control.
+-- @tfield string key The key to trigger an event.
+-- @tfield string keysym Same as key, but return the name of the key symbol. It
+--   can be identical to key, but for characters like '.' it will return
+--   'period'.
+-- @tfield table modifiers The modifier key that should be pressed while the
+--   key is pressed. An array with all the modifiers. Valid modifiers are: Any,
+--   Mod1, Mod2, Mod3, Mod4, Mod5, Shift, Lock and Control.
 -- @table key
 
 --- Add a signal.
 --
--- @param name A signal name.
--- @param func A function to call when the signal is emitted.
+-- @tparam string name A signal name.
+-- @tparam function func A function to call when the signal is emitted.
 -- @function connect_signal
 
 --- Remove a signal.
 --
--- @param name A signal name.
--- @param func A function to remove.
+-- @tparam string name A signal name.
+-- @tparam function func A function to remove.
 -- @function disconnect_signal
 
 --- Emit a signal.
 --
--- @param name A signal name.
+-- @tparam string name A signal name.
 -- @param[opt] ... Various arguments.
 -- @function emit_signal
 
 --- Get the number of instances.
 --
--- @return The number of key objects alive.
+-- @treturn number The number of key objects alive.
 -- @function instances
diff --git a/lib/awful/key.lua.in b/lib/awful/key.lua.in
index 1170d368..bb6a1286 100644
--- a/lib/awful/key.lua.in
+++ b/lib/awful/key.lua.in
@@ -25,14 +25,19 @@ local ignore_modifiers = { "Lock", "Mod2" }
 
 --- Create a new key to use as binding.
 -- This function is useful to create several keys from one, because it will use
--- the ignore_modifier variable to create more key with or without the ignored
--- modifiers activated.
+-- the ignore_modifier variable to create several keys with and without the
+-- ignored modifiers activated.
 -- For example if you want to ignore CapsLock in your keybinding (which is
--- ignored by default by this function), creating key binding with this function
--- will return 2 key objects: one with CapsLock on, and the other one with
--- CapsLock off.
--- @see key
--- @return A table with one or several key objects.
+-- ignored by default by this function), creating a key binding with this
+-- function will return 2 key objects: one with CapsLock on, and another one
+-- with CapsLock off.
+-- @see key.key
+-- @tparam table mod A list of modifier keys.  Valid modifiers are: Any, Mod1,
+--   Mod2, Mod3, Mod4, Mod5, Shift, Lock and Control.
+-- @tparam string _key The key to trigger an event.
+-- @tparam function press Callback for when the key is pressed.
+-- @tparam function release Callback for when the key is released.
+-- @treturn table A table with one or several key objects.
 function key.new(mod, _key, press, release)
     local ret = {}
     local subsets = util.subsets(ignore_modifiers)