From 74f3e40c935792477ea4a9fb3b3a7823787ec25a Mon Sep 17 00:00:00 2001
From: ArenaL5 <arenal5@gmx.com>
Date: Thu, 20 Feb 2020 03:25:37 +0100
Subject: [PATCH] Document the newly exposed `awful.key.keygroups`

Also, more detail in the descriptions of properties `description` and `keygroup`

Signed-off-by: ArenaL5 <arenal5@gmx.com>
---
 lib/awful/key.lua | 38 ++++++++++++++++++++++++++++++++------
 1 file changed, 32 insertions(+), 6 deletions(-)

diff --git a/lib/awful/key.lua b/lib/awful/key.lua
index 661f3c761..7879be2df 100644
--- a/lib/awful/key.lua
+++ b/lib/awful/key.lua
@@ -60,9 +60,9 @@ local gobject = require("gears.object")
 -- @property modifiers
 -- @tparam table modifiers
 
---- The key description.
+--- The description of the function run from a key binding.
 --
--- This is used, for example, by the `awful.hotkey_popup`.
+-- This is used, for example, by `awful.hotkeys_popup`.
 --
 -- @property description
 -- @param string
@@ -74,9 +74,9 @@ local gobject = require("gears.object")
 -- @property name
 -- @param string
 
---- The key group.
+--- The key group bound to a function in a key binding.
 --
--- This is used, for example, by the `awful.hotkey_popup`.
+-- This is used, for example, by `awful.hotkeys_popup`.
 --
 -- @property group
 -- @param string
@@ -298,9 +298,35 @@ local function new_common(mod, _keys, press, release, data)
     return setmetatable(ret, obj_mt)
 end
 
+--- The default definitions of keygroups.
+--
+-- A definition for a keygroup (say, **arrows**) can be accessed by indexing
+-- this table (e.g. `awful.key.keygroups.arrows`).
+--
+-- Every definition is given as an array, where every element is another array
+-- with the following structure:
+--
+-- * The first element is a string representing a key, in any format the
+-- property `key` will allow.
+-- * The second element is a value. Key bindings created by `awful.key` and a
+-- `keygroup` are bound to a 1-parameter function, whose parameter is this
+-- second element.
+--
+-- As an example, **arrows** is currently defined thus:
+--
+--    arrows = {
+--        {"Left"  , "Left"  },
+--        {"Right" , "Right" },
+--        {"Up"    , "Up"    },
+--        {"Down"  , "Down"  },
+--    }
+--
+-- This table is acessed internally by Awesome. Users will usually use key
+-- bindings with the property `keygroup` instead of accessing this table
+-- directly.
+-- @name awful.key.keygroups
+-- @class table
 key.keygroups = {
-    -- Left: the keycode in a format which regular awful.key understands.
-    -- Right: the argument of the function ran upon executing the key binding.
     numrow = {},
     arrows = {
         {"Left"  , "Left"  },