doc: Move inline usage to example files

Signed-off-by: Lucas Schwiderski <lucas@lschwiderski.de>

lib/awful/titlebar.lua

@@ -514,9 +514,7 @@ end
 -- values for the client (`c`) and the titlebar position (`args.position`),
 -- the previous titlebar will be removed and replaced by the new one.
 --
---    awful.titlebar(c)
---    awful.titlebar(c, { position = "left" })
---    awful.titlebar(c, { bg_normal = beautiful.fg, fg_normal = beautiful.bg })
+-- @DOC_awful_titlebar_constructor_EXAMPLE@
 --
 -- @tparam client c The client the titlebar will be attached to.
 -- @tparam[opt={}] table args A table with extra arguments for the titlebar.

objects/tag.c

@@ -219,33 +219,12 @@ lua_class_t tag_class;
  * It is emitted on the global `tag` class rather than individual tag objects.
  * This default handler is part of `rc.lua`:
  *
- *    tag.connect_signal("request::default_layouts", function()
- *        awful.layout.append_default_layouts({
- *            awful.layout.suit.floating,
- *            awful.layout.suit.tile,
- *            awful.layout.suit.tile.left,
- *            awful.layout.suit.tile.bottom,
- *            awful.layout.suit.tile.top,
- *            awful.layout.suit.fair,
- *            awful.layout.suit.fair.horizontal,
- *            awful.layout.suit.spiral,
- *            awful.layout.suit.spiral.dwindle,
- *            awful.layout.suit.max,
- *            awful.layout.suit.max.fullscreen,
- *            awful.layout.suit.magnifier,
- *            awful.layout.suit.corner.nw,
- *        })
- *    end)
+ * @DOC_awful_tag_request_default_layouts_EXAMPLE@
  *
  * External modules can also use this signal to dynamically add additional
  * default layouts.
  *
- *    tag.connect_signal("request::default_layouts", function()
- *        awful.layout.append_default_layouts({
- *            custom_module.layout_1,
- *            custom_module.layout_2,
- *        })
- *    end)
+ * @DOC_awful_tag_module_default_layouts_EXAMPLE@
  *
  * @signal request::default_layouts
  * @tparam string context The context (currently always "startup").

tests/examples/awful/tag/module_default_layouts.lua

@@ -0,0 +1,18 @@
+--DOC_ASTERISK --DOC_NO_USAGE --DOC_HIDE_START
+local awful     = require("awful")
+local custom_module = {
+    layout_1 = awful.layout.suit.floating,
+    layout_2 = awful.layout.suit.tile,
+}
+
+--DOC_HIDE_END
+
+    tag.connect_signal("request::default_layouts", function()
+        awful.layout.append_default_layouts({
+            custom_module.layout_1,
+            custom_module.layout_2,
+        })
+    end)
+
+--DOC_HIDE_START
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/awful/tag/request_default_layouts.lua

@@ -0,0 +1,25 @@
+--DOC_ASTERISK --DOC_NO_USAGE --DOC_HIDE_START
+local awful     = require("awful")
+
+--DOC_HIDE_END
+
+    tag.connect_signal("request::default_layouts", function()
+        awful.layout.append_default_layouts({
+            awful.layout.suit.floating,
+            awful.layout.suit.tile,
+            awful.layout.suit.tile.left,
+            awful.layout.suit.tile.bottom,
+            awful.layout.suit.tile.top,
+            awful.layout.suit.fair,
+            awful.layout.suit.fair.horizontal,
+            awful.layout.suit.spiral,
+            awful.layout.suit.spiral.dwindle,
+            awful.layout.suit.max,
+            awful.layout.suit.max.fullscreen,
+            awful.layout.suit.magnifier,
+            awful.layout.suit.corner.nw,
+        })
+    end)
+
+--DOC_HIDE_START
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/awful/titlebar/constructor.lua

@@ -0,0 +1,69 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_START
+local awful = { titlebar = require("awful.titlebar"),
+                button   = require("awful.button"),
+              }
+local beautiful = require("beautiful")
+local wibox = require("wibox")
+local gears = {table = require("gears.table")}
+
+screen[1]._resize { width = 646, height = 182 }
+
+local c
+
+local clients = {
+    client.gen_fake{ x = 10,  y = 10, height = 160, width = 200 },
+    client.gen_fake{ x = 222, y = 10, height = 160, width = 200 },
+    client.gen_fake{ x = 434, y = 10, height = 160, width = 200 },
+}
+
+local function setup(bar)
+    bar:setup {
+        awful.titlebar.widget.iconwidget(c),
+        {
+            align  = "center",
+            widget = awful.titlebar.widget.titlewidget(c)
+        },
+        {
+            awful.titlebar.widget.floatingbutton (c),
+            awful.titlebar.widget.maximizedbutton(c),
+            awful.titlebar.widget.stickybutton   (c),
+            awful.titlebar.widget.ontopbutton    (c),
+            awful.titlebar.widget.closebutton    (c),
+            layout = wibox.layout.fixed.horizontal
+        },
+        layout = wibox.layout.align.horizontal
+    }
+end
+
+c = clients[1]
+setup(
+--DOC_HIDE_END
+
+    -- Create default titlebar
+    awful.titlebar(c)
+
+--DOC_HIDE_START
+)
+
+c = clients[2]
+setup(
+--DOC_HIDE_END
+
+    -- Create titlebar on the client's bottom edge
+    awful.titlebar(c, { position = "bottom" })
+
+--DOC_HIDE_START
+)
+
+c = clients[3]
+setup(
+--DOC_HIDE_END
+
+    -- Create titlebar with inverted colors
+    awful.titlebar(c, { bg_normal = beautiful.fg_normal, fg_normal = beautiful.bg_normal })
+
+--DOC_HIDE_START
+)
+
+return {hide_lines=true}
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80