doc: Move inline usage to example files

lib/awful/key.lua

@@ -9,42 +9,18 @@
 --
 -- This example shows how to define a basic key object:
 --
---    awful.key({ "Mod4", "Shift" }, 'a',
+-- @DOC_text_awful_key_constructor_default_EXAMPLE@
---      function () print("The `Mod4` + `Shift` + `a` combo is pressed") end,
---      function () print("The `Mod4` + `Shift` + `a` combo is released") end)
 --
 -- This example shows how to define the same basic key object with the
 -- declarative pattern:
 --
---    awful.key {
+-- @DOC_text_awful_key_constructor_declarative_EXAMPLE@
---      modifiers = { "Mod4", "Shift" },
---      key = 'a',
---      on_press = function ()
---         print("The `Mod4` + `Shift` + `a` combo is pressed")
---      end,
---      on_release = function ()
---         print("The `Mod4` + `Shift` + `a` combo is released")
---      end
---    }
 --
 -- This second example of a key definition uses the numrow keygroup. In this
 -- example, we define a key object, that select the tag to show according to
 -- the key index from the numrow.
 --
---    local show_tag_by_numrow_index = awful.key {
+-- @DOC_text_awful_key_constructor_keygroup_EXAMPLE@
---      modifiers = { "Mod4" },
---      keygroup = awful.key.keygroup.NUMROW,
---      description = "only view tag",
---      group = "tag",
---      on_press = function (index)
---         local screen = awful.screen.focused()
---         local tag = screen.tags[index]
---
---         if tag then
---             tag:view_only()
---         end
---      end
---    }
 --
 -- @author Julien Danjou <julien@danjou.info>
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>

tests/examples/text/awful/key/constructor/declarative.lua

@@ -0,0 +1,16 @@
+--DOC_NO_USAGE
+
+local awful = require("awful") --DOC_HIDE
+
+    awful.key {
+        modifiers = { "Mod4", "Shift" },
+        key = 'a',
+        on_press = function ()
+            print("The `Mod4` + `Shift` + `a` combo is pressed")
+        end,
+        on_release = function ()
+            print("The `Mod4` + `Shift` + `a` combo is released")
+        end
+    }
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/text/awful/key/constructor/default.lua

@@ -0,0 +1,9 @@
+--DOC_NO_USAGE
+
+local awful = require("awful") --DOC_HIDE
+
+    awful.key({ "Mod4", "Shift" }, "a",
+        function () print("The `Mod4` + `Shift` + `a` combo is pressed") end,
+        function () print("The `Mod4` + `Shift` + `a` combo is released") end)
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/text/awful/key/constructor/keygroup.lua

@@ -0,0 +1,21 @@
+--DOC_NO_USAGE
+
+local awful = require("awful") --DOC_HIDE
+
+-- luacheck: ignore unused variable show_tag_by_numrow_index --DOC_HIDE
+    local show_tag_by_numrow_index = awful.key {
+        modifiers = { "Mod4" },
+        keygroup = awful.key.keygroup.NUMROW,
+        description = "only view tag",
+        group = "tag",
+        on_press = function (index)
+            local screen = awful.screen.focused()
+            local tag = screen.tags[index]
+
+            if tag then
+                tag:view_only()
+            end
+        end
+    }
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80