diff --git a/lib/awful/mouse/init.lua b/lib/awful/mouse/init.lua
index f42b0d1a0..0411e3434 100644
--- a/lib/awful/mouse/init.lua
+++ b/lib/awful/mouse/init.lua
@@ -35,28 +35,29 @@ mouse.wibox = {}
 --
 -- @DOC_screen_client_snap_EXAMPLE@
 --
--- @tfield integer awful.mouse.snap.default_distance
+-- @tfield integer snap.default_distance
 -- @tparam[opt=8] integer default_distance
 -- @see awful.mouse.snap
 
 --- The default distance before activating screen edge snap.
--- @tfield integer awful.mouse.snap.aerosnap_distance
--- @tparam[opt=16] integer default_distance
+-- @tfield integer snap.aerosnap_distance
+-- @tparam[opt=16] integer aerosnap_distance
 -- @see awful.mouse.snap
 
 --- Enable screen edges snapping.
 --
---
---
 --@DOC_awful_placement_aero_snap_EXAMPLE@
 --
--- @tfield[opt=true] boolean awful.mouse.snap.edge_enabled
+-- @tfield[opt=true] boolean snap.edge_enabled
+-- @tparam boolean edge_enabled
 
 --- Enable client to client snapping.
--- @tfield[opt=true] boolean awful.mouse.snap.client_enabled
+-- @tfield[opt=true] boolean snap.client_enabled
+-- @tparam boolean client_enabled
 
 --- Enable changing tag when a client is dragged to the edge of the screen.
--- @tfield[opt=false] integer awful.mouse.drag_to_tag.enabled
+-- @tfield[opt=false] boolean drag_to_tag.enabled
+-- @tparam boolean enabled
 
 --- The snap outline background color.
 -- @beautiful beautiful.snap_bg
diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua
index 6ad36e905..bb628bf62 100644
--- a/lib/awful/tag.lua
+++ b/lib/awful/tag.lua
@@ -349,7 +349,7 @@ function tag.find_fallback(screen, invalids)
     end
 end
 
---- When all clients are removed from the tag.
+--- Emitted when all clients are removed from the tag.
 -- @signal cleared
 -- @see clear
 
@@ -1841,20 +1841,25 @@ capi.client.connect_signal("untagged", client_untagged)
 capi.client.connect_signal("tagged", client_tagged)
 capi.tag.connect_signal("request::select", tag.object.view_only)
 
---- True when a tagged client is urgent
+--- Emitted when the number of urgent clients on this tag changes.
 -- @signal property::urgent
+-- @param boolean `true` if there is at least one urgent client on the tag.
 -- @see client.urgent
 
---- The number of urgent tagged clients
+--- Emitted when the number of urgent clients on this tag changes.
 -- @signal property::urgent_count
+-- @param integer The number of urgent clients on the tag.
 -- @see client.urgent
 
 --- Emitted when a screen is removed.
+--
 -- This can be used to salvage existing tags by moving them to a new
--- screen (or creating a virtual screen). By default, there is no
--- handler for this request. The tags will be deleted. To prevent
--- this, an handler for this request must simply set a new screen
+-- screen (or creating a virtual screen).
+--
+-- By default, there is no handler for this request and the tags will be deleted.
+-- To prevent this, an handler for this request must simply set a new screen
 -- for the tag.
+--
 -- @signal request::screen
 -- @tparam string context Why it was called.
 
diff --git a/lib/awful/titlebar.lua b/lib/awful/titlebar.lua
index afc734f0a..ae91c664c 100644
--- a/lib/awful/titlebar.lua
+++ b/lib/awful/titlebar.lua
@@ -505,20 +505,33 @@ local function get_children_by_id(self, name)
 end
 
 
---- Get a client's titlebar.
--- @tparam client c The client for which a titlebar is wanted.
+--- Create a new titlebar for the given client.
+--
+-- Every client can hold up to four titlebars, one for each side (i.e. each
+-- value of `args.position`).
+--
+-- If this constructor is called again with the same
+-- values for the client (`c`) and the titlebar position (`args.position`),
+-- the previous titlebar will be removed and replaced by the new one.
+--
+-- @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.
--- @tparam[opt=font.height*1.5] number args.size The height of the titlebar.
--- @tparam[opt=top] string args.position" values are `top`,
--- `left`, `right` and `bottom`.
--- @tparam[opt=top] string args.bg_normal
--- @tparam[opt=top] string args.bg_focus
--- @tparam[opt=top] string args.bgimage_normal
--- @tparam[opt=top] string args.bgimage_focus
--- @tparam[opt=top] string args.fg_normal
--- @tparam[opt=top] string args.fg_focus
--- @tparam[opt=top] string args.font
+-- @tparam[opt=font.height*1.5] number args.size The size of the titlebar. Will
+--   be interpreted as `height` for horizontal titlebars or as `width` for
+--   vertical titlebars.
+-- @tparam[opt="top"] string args.position Possible values are `"top"`,
+-- `"left"`, `"right"` and `"bottom"`.
+-- @tparam[opt] string args.bg_normal
+-- @tparam[opt] string args.bg_focus
+-- @tparam[opt] string args.bgimage_normal
+-- @tparam[opt] string args.bgimage_focus
+-- @tparam[opt] string args.fg_normal
+-- @tparam[opt] string args.fg_focus
+-- @tparam[opt] string args.font
 -- @constructorfct awful.titlebar
+-- @treturn wibox.drawable The newly created titlebar object.
 local function new(c, args)
     args = args or {}
     local position = args.position or "top"
@@ -578,10 +591,10 @@ local function new(c, args)
     return ret
 end
 
---- Show a client's titlebar.
+--- Show the client's titlebar.
 -- @param c The client whose titlebar is modified
--- @param[opt] position The position of the titlebar. Must be one of "left",
---   "right", "top", "bottom". Default is "top".
+-- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`,
+--   `"right"`, `"top"`, `"bottom"`.
 -- @staticfct awful.titlebar.show
 -- @request client titlebars show granted Called when `awful.titlebar.show` is
 --  called.
@@ -594,20 +607,20 @@ function titlebar.show(c, position)
     new(c, args)
 end
 
---- Hide a client's titlebar.
+--- Hide the client's titlebar.
 -- @param c The client whose titlebar is modified
--- @param[opt] position The position of the titlebar. Must be one of "left",
---   "right", "top", "bottom". Default is "top".
+-- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`,
+--   `"right"`, `"top"`, `"bottom"`.
 -- @staticfct awful.titlebar.hide
 function titlebar.hide(c, position)
     position = position or "top"
     get_titlebar_function(c, position)(c, 0)
 end
 
---- Toggle a client's titlebar, hiding it if it is visible, otherwise showing it.
+--- Toggle the client's titlebar, hiding it if it is visible, otherwise showing it.
 -- @param c The client whose titlebar is modified
--- @param[opt] position The position of the titlebar. Must be one of "left",
---   "right", "top", "bottom". Default is "top".
+-- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`,
+--   `"right"`, `"top"`, `"bottom"`.
 -- @staticfct awful.titlebar.toggle
 -- @request client titlebars toggle granted Called when `awful.titlebar.toggle` is
 --  called.
@@ -649,9 +662,12 @@ local function update_on_signal(c, signal, widget)
     table.insert(widgets, widget)
 end
 
---- Create a new titlewidget. A title widget displays the name of a client.
+--- Create a new title widget.
+--
+-- A title widget displays the name of a client.
 -- Please note that this returns a textbox and all of textbox' API is available.
 -- This way, you can e.g. modify the font that is used.
+--
 -- @param c The client for which a titlewidget should be created.
 -- @return The title widget.
 -- @constructorfct awful.titlebar.widget.titlewidget
@@ -667,9 +683,12 @@ function titlebar.widget.titlewidget(c)
     return ret
 end
 
---- Create a new icon widget. An icon widget displays the icon of a client.
+--- Create a new icon widget.
+--
+-- An icon widget displays the icon of a client.
 -- Please note that this returns an imagebox and all of the imagebox' API is
 -- available. This way, you can e.g. disallow resizes.
+--
 -- @param c The client for which an icon widget should be created.
 -- @return The icon widget.
 -- @constructorfct awful.titlebar.widget.iconwidget
@@ -677,13 +696,16 @@ function titlebar.widget.iconwidget(c)
     return clienticon(c)
 end
 
---- Create a new button widget. A button widget displays an image and reacts to
+--- Create a new button widget.
+--
+-- A button widget displays an image and reacts to
 -- mouse clicks. Please note that the caller has to make sure that this widget
--- gets redrawn when needed by calling the returned widget's update() function.
+-- gets redrawn when needed by calling the returned widget's `:update()` method.
 -- The selector function should return a value describing a state. If the value
--- is a boolean, either "active" or "inactive" are used. The actual image is
--- then found in the theme as "titlebar_[name]_button_[normal/focus]_[state]".
+-- is a boolean, either `"active"` or `"inactive"` are used. The actual image is
+-- then found in the theme as `titlebar_[name]_button_[normal/focus]_[state]`.
 -- If that value does not exist, the focused state is ignored for the next try.
+--
 -- @param c The client for which a button is created.
 -- @tparam string name Name of the button, used for accessing the theme and
 --   in the tooltip.
diff --git a/lib/gears/table.lua b/lib/gears/table.lua
index 552d0b7ad..b98aa66d8 100644
--- a/lib/gears/table.lua
+++ b/lib/gears/table.lua
@@ -39,27 +39,31 @@ function gtable.join(...)
     return ret
 end
 
---- Override elements in the first table by the one in the second.
+--- Override elements in the target table with values from the source table.
 --
 -- Note that this method doesn't copy entries found in `__index`.
+-- Nested tables are copied by reference and not recursed into.
 --
--- @tparam table t the table to be overriden
--- @tparam table set the table used to override members of `t`
--- @tparam[opt=false] bool raw Use rawset (avoid the metatable)
--- @treturn table t (for convenience)
+-- @tparam table target The target table. Values from `source` will be copied
+--   into this table.
+-- @tparam table source The source table. Its values will be copied into
+--   `target`.
+-- @tparam[opt=false] bool raw If `true`, values will be assigned with `rawset`.
+--   This will bypass metamethods on `target`.
+-- @treturn table The target table.
 -- @staticfct gears.table.crush
-function gtable.crush(t, set, raw)
+function gtable.crush(target, source, raw)
     if raw then
-        for k, v in pairs(set) do
-            rawset(t, k, v)
+        for k, v in pairs(source) do
+            rawset(target, k, v)
         end
     else
-        for k, v in pairs(set) do
-            t[k] = v
+        for k, v in pairs(source) do
+            target[k] = v
         end
     end
 
-    return t
+    return target
 end
 
 --- Pack all elements with an integer key into a new table.
@@ -225,7 +229,8 @@ end
 --- Clone a table.
 --
 -- @tparam table t The table to clone.
--- @tparam[opt=true] bool deep Create a deep clone?
+-- @tparam[opt=true] bool deep If `true`, recurse into nested tables to create
+--   a deep clone.
 -- @treturn table A clone of `t`.
 -- @staticfct gears.table.clone
 function gtable.clone(t, deep)
@@ -306,17 +311,23 @@ function gtable.iterate(t, filter, start)
     end
 end
 
---- Merge items from one table to another one.
+--- Merge items from the source table into the target table.
 --
--- @tparam table t The container table
--- @tparam table set The mixin table.
--- @treturn table (for convenience).
+-- Note that this only considers the array part of `source` (same semantics
+-- as `ipairs`).
+-- Nested tables are copied by reference and not recursed into.
+--
+-- @tparam table target The target table. Values from `source` will be copied
+--   into this table.
+-- @tparam table source The source table. Its values will be copied into
+--   `target`.
+-- @treturn table The target table.
 -- @staticfct gears.table.merge
-function gtable.merge(t, set)
-    for _, v in ipairs(set) do
-        table.insert(t, v)
+function gtable.merge(target, source)
+    for _, v in ipairs(source) do
+        table.insert(target, v)
     end
-    return t
+    return target
 end
 
 --- Update the `target` table with entries from the `new` table.
@@ -403,7 +414,7 @@ end
 
 --- Map a function to a table.
 --
--- The function is applied to each value on the table, returning a modified
+-- The function is applied to each value in the table, returning a modified
 -- table.
 --
 -- @tparam function f The function to be applied to each value in the table.
diff --git a/lib/gears/timer.lua b/lib/gears/timer.lua
index c2f2f99ec..20653a4bb 100644
--- a/lib/gears/timer.lua
+++ b/lib/gears/timer.lua
@@ -194,13 +194,17 @@ function timer.new(args)
     return ret
 end
 
---- Create a timeout for calling some callback function.
--- When the callback function returns true, it will be called again after the
--- same timeout. If false is returned, no more calls will be done. If the
--- callback function causes an error, no more calls are done.
+--- Create a simple timer for calling the `callback` function continuously.
+--
+-- This is a small wrapper around `gears.timer`, that creates a timer based on
+-- `callback`.
+-- The timer will run continuously and call `callback` every `timeout` seconds.
+-- It is stopped when `callback` returns `false`, when `callback` throws an
+-- error or when the `:stop()` method is called on the return value.
+--
 -- @tparam number timeout Timeout in seconds (e.g. 1.5).
 -- @tparam function callback Function to run.
--- @treturn timer The timer object that was set up.
+-- @treturn timer The new timer object.
 -- @staticfct gears.timer.start_new
 -- @see gears.timer.weak_start_new
 function timer.start_new(timeout, callback)
@@ -215,14 +219,18 @@ function timer.start_new(timeout, callback)
     return t
 end
 
---- Create a timeout for calling some callback function.
--- This function is almost identical to `gears.timer.start_new`. The only difference
--- is that this does not prevent the callback function from being garbage
--- collected. After the callback function was collected, the timer returned
--- will automatically be stopped.
+--- Create a simple timer for calling the `callback` function continuously.
+--
+-- This function is almost identical to `gears.timer.start_new`. The only
+-- difference is that this does not prevent the callback function from being
+-- garbage collected.
+-- In addition to the conditions in `gears.timer.start_new`,
+-- this timer will also stop if `callback` was garbage collected since the
+-- previous run.
+--
 -- @tparam number timeout Timeout in seconds (e.g. 1.5).
 -- @tparam function callback Function to start.
--- @treturn timer The timer object that was set up.
+-- @treturn timer The new timer object.
 -- @staticfct gears.timer.weak_start_new
 -- @see gears.timer.start_new
 function timer.weak_start_new(timeout, callback)
@@ -249,7 +257,7 @@ function timer.run_delayed_calls_now()
     delayed_calls = {}
 end
 
---- Call the given function at the end of the current main loop iteration
+--- Call the given function at the end of the current GLib event loop iteration.
 -- @tparam function callback The function that should be called
 -- @param ... Arguments to the callback function
 -- @staticfct gears.timer.delayed_call
diff --git a/objects/client.c b/objects/client.c
index 909a317e1..36db11c3f 100644
--- a/objects/client.c
+++ b/objects/client.c
@@ -136,7 +136,7 @@ lua_class_t client_class;
  * @table awful.client.object
  */
 
-/** AwesomeWM is about to scan for existing clients.
+/** Emitted when AwesomeWM is about to scan for existing clients.
  *
  * Connect to this signal when code needs to be executed after screens are
  * initialized, but before clients are added.
@@ -145,7 +145,7 @@ lua_class_t client_class;
  * @classsignal
  */
 
-/** AwesomeWM is done scanning for clients.
+/** Emitted when AwesomeWM is done scanning for clients.
  *
  * This is emitted before the `startup` signal and after the `scanning` signal.
  *
@@ -153,23 +153,24 @@ lua_class_t client_class;
  * @classsignal
  */
 
-/** When a client gains focus.
+/** Emitted when a client gains focus.
  * @signal focus
  * @classsignal
  */
 
-/** Before manage, after unmanage, and when clients swap.
+/** Emitted before `request::manage`, after `request::unmanage`,
+ * and when clients swap.
  * @signal list
  * @classsignal
  */
 
-/** When 2 clients are swapped
+/** Emitted when 2 clients are swapped
  * @tparam client client The other client
  * @tparam boolean is_source If self is the source or the destination of the swap
  * @signal swapped
  */
 
-/** When a new client appears and gets managed by Awesome.
+/** Emitted when a new client appears and gets managed by Awesome.
  *
  * This request should be implemented by code which track the client. It isn't
  * recommended to use this to initialize the client content. This use case is
@@ -188,7 +189,7 @@ lua_class_t client_class;
  * @classsignal
  */
 
-/** When a client is going away.
+/** Emitted when a client is going away.
  *
  * Each places which store `client` objects in non-weak table or whose state
  * depend on the current client should answer this request.
@@ -216,32 +217,32 @@ lua_class_t client_class;
  * @deprecatedsignal unmanage
  */
 
-/** When a mouse button is pressed in a client.
+/** Emitted when a mouse button is pressed in a client.
  * @signal button::press
  */
 
-/** When a mouse button is released in a client.
+/** Emitted when a mouse button is released in a client.
  *
  * @signal button::release
  */
 
-/** When the mouse enters a client.
+/** Emitted when the mouse enters a client.
  *
  * @signal mouse::enter
  */
 
-/** When the mouse leaves a client.
+/** Emitted when the mouse leaves a client.
  *
  * @signal mouse::leave
  */
 
 /**
- * When the mouse moves within a client.
+ * Emitted when the mouse moves within a client.
  *
  * @signal mouse::move
  */
 
-/** When a client should get activated (focused and/or raised).
+/** Emitted when a client should get activated (focused and/or raised).
  *
  * **Contexts are:**
  *
@@ -279,7 +280,7 @@ lua_class_t client_class;
  * @classsignal
  */
 
-/** When an event could lead to the client being activated.
+/** Emitted when an event could lead to the client being activated.
  *
  * This is an layer "on top" of `request::activate` for event which are not
  * actual request for activation/focus, but where "it would be nice" if the
@@ -300,7 +301,7 @@ lua_class_t client_class;
  *
  */
 
-/** When something request a client geometry to be modified.
+/** Emitted when something request a client's geometry to be modified.
  *
  * @signal request::geometry
  * @tparam client c The client
@@ -315,23 +316,39 @@ lua_class_t client_class;
  * @classsignal
  */
 
-/** When the tag requests to be moved to a tag or needs a new tag.
+/** Emitted when a client requests to be moved to a tag or needs a new tag.
  *
  * @signal request::tag
+ * @tparam client c The client requesting a new tag.
  * @classsignal
  */
 
-/** When the client requests to become urgent.
+/** Emitted when any client's `urgent` property changes.
+ *
+ * Emitted both when `urgent = true` and `urgent = false`, so you will likely
+ * want to check `c.urgent` within the signal callback.
+ *
+ *    client.connect_signal("property::urgent", function(c)
+ *        if c.urgent then
+ *            naughty.notify {
+ *                title = "Urgent client",
+ *                message = c.name,
+ *            }
+ *        end
+ *    end)
  *
  * @signal request::urgent
+ * @tparam client c The client whose property changed.
  * @classsignal
  */
 
-/** Emitted during startup to gather the default client mousebindings.
+/** Emitted once to request default client mousebindings during the initial
+ * startup sequence.
  *
- * This signals gives a chance to all module to register new client keybindings.
- * Assuming the client rules does not overwrite them with the `keys` property,
- * they will be added to all clients.
+ * This signal gives all modules a chance to register their default client
+ * mousebindings.
+ * They will then be added to all new clients, unless rules overwrite them via
+ * the `buttons` property.
  *
  * @signal request::default_mousebindings
  * @tparam string context The reason why the signal was sent (currently always
@@ -339,41 +356,30 @@ lua_class_t client_class;
  * @classsignal
 */
 
-/** Emitted during startup to gather the default client keybindings.
+/** Emitted once to request default client keybindings during the initial
+ * startup sequence.
  *
- * This signals gives a chance to all module to register new client keybindings.
- * Assuming the client rules does not overwrite them with the `keys` property,
- * they will be added to all clients.
+ * This signal gives all modules a chance to register their default client
+ * keybindings.
+ * They will then be added to all new clients, unless rules overwrite them via
+ * the `keys` property.
  *
  * @signal request::default_keybindings
  * @tparam string context The reason why the signal was sent (currently always
- *  `startup`).
- * @classsignal
- */
-
-/** Sent once when AwesomeWM starts to add default keybindings.
- *
- * Keybindings can be set directly on clients. Actually, older version of
- * AwesomeWM did that through the rules. However this makes it impossible for
- * auto-configured modules to add their own keybindings. Using the signals,
- * `rc.lua` or any module can cleanly manage keybindings.
- *
- * @signal request::default_keybindings
- * @tparam string context The context (currently always "startup").
  * @classsignal
  * @request client default_keybindings startup granted Sent when AwesomeWM starts.
  */
 
-/** When a client gets tagged.
+/** Emitted when a client gets tagged.
  * @signal tagged
  * @tparam tag t The tag object.
  */
 
-/** When a client gets unfocused.
+/** Emitted when a client gets unfocused.
  * @signal unfocus
  */
 
-/** When a client gets untagged.
+/** Emitted when a client gets untagged.
  * @signal untagged
  * @tparam tag t The tag object.
  */
@@ -404,13 +410,13 @@ lua_class_t client_class;
 /**
  * The focused `client` or nil (in case there is none).
  *
- * It is not recommanded to set the focused client using
- * this property. Please use `c:activate{}` instead of
+ * It is not recommended to set the focused client using
+ * this property. Please use @{client.activate} instead of
  * `client.focus = c`. Setting the focus directly bypasses
  * all the filters and emits fewer signals, which tend to
  * cause unwanted side effects and make it harder to alter
  * the code behavior in the future. It usually takes *more*
- * code to use this rather than `:activate{}` because all
+ * code to use this rather than @{client.activate} because all
  * the boilerplate code (such as `c:raise()`) needs to be
  * added everywhere.
  *
@@ -591,12 +597,12 @@ lua_class_t client_class;
  */
 
 /**
- * The machine client is running on.
+ * The machine the client is running on.
  *
- * X11 windows can "live" in another computer but shown
+ * X11 windows can "live" in one computer but be shown
  * in another one. This is called "network transparency"
  * and is either used directly by allowing remote windows
- * using the `xhosts` command for using proxies such as
+ * using the `xhosts` command or using proxies such as
  * `ssh -X` or `ssh -Y`.
  *
  * According to EWMH, this property contains the value
@@ -622,7 +628,7 @@ lua_class_t client_class;
  * This property holds the client icon closest to the size configured via
  * @{awesome.set_preferred_icon_size}.
  *
- * It is not a path or an "real" file. Rather, it is already a bitmap surface.
+ * It is not a path or a "real" file. Rather, it is already a bitmap surface.
  *
  * Typically you would want to use @{awful.widget.clienticon} to get this as a
  * widget.
@@ -649,6 +655,14 @@ lua_class_t client_class;
  * The available sizes of client icons. This is a table where each entry
  * contains the width and height of an icon.
  *
+ * Example:
+ *
+ *    {
+ *      { 24, 24 },
+ *      { 32, 32 },
+ *      { 64, 64 },
+ *    }
+ *
  * @property icon_sizes
  * @tparam table sizes
  * @propemits false false
diff --git a/objects/tag.c b/objects/tag.c
index f41ce6545..ffd28d41b 100644
--- a/objects/tag.c
+++ b/objects/tag.c
@@ -205,7 +205,7 @@
 
 lua_class_t tag_class;
 
-/** When a tag requests to be selected.
+/** Emitted when a tag requests to be selected.
  * @signal request::select
  * @tparam string context The reason why it was called.
  * @request tag select ewmh granted When the client request to be moved to a
@@ -214,11 +214,17 @@ lua_class_t tag_class;
  */
 
 /**
- * This signal is emitted to fill the list of default layouts.
+ * This signal is emitted to request the list of default layouts.
  *
  * It is emitted on the global `tag` class rather than individual tag objects.
- * The default handler is part of `rc.lua`. New modules can also use this signal
- * to dynamically add new layouts to the list of default layouts.
+ * This default handler is part of `rc.lua`:
+ *
+ * @DOC_awful_tag_request_default_layouts_EXAMPLE@
+ *
+ * External modules can also use this signal to dynamically add additional
+ * default layouts.
+ *
+ * @DOC_awful_tag_module_default_layouts_EXAMPLE@
  *
  * @signal request::default_layouts
  * @tparam string context The context (currently always "startup").
@@ -240,12 +246,12 @@ lua_class_t tag_class;
  * @tparam table hints A, currently empty, table with hints.
  */
 
-/** When a client gets tagged with this tag.
+/** Emitted when a client gets tagged with this tag.
  * @signal tagged
  * @tparam client c The tagged client.
  */
 
-/** When a client gets untagged with this tag.
+/** Emitted when a client gets untagged with this tag.
  * @signal untagged
  * @tparam client c The untagged client.
  */
diff --git a/tests/examples/CMakeLists.txt b/tests/examples/CMakeLists.txt
index f7f2eb857..501a2fab3 100644
--- a/tests/examples/CMakeLists.txt
+++ b/tests/examples/CMakeLists.txt
@@ -88,14 +88,28 @@ function(escape_string variable content escaped_content line_prefix)
     string(REGEX REPLACE "\n" ";" var_lines "${variable}")
 
     set(tmp_output ${content})
+    set(section OFF)
     foreach (LINE ${var_lines})
 
         # ;; will drop the line, but " ;" will create an empty line
         string(REGEX REPLACE "--DOC_NEWLINE" " " LINE "${LINE}")
 
-        if(NOT LINE MATCHES "^.*--DOC_[A-Z]+")
+        # Check for section start marker
+        if(LINE MATCHES "^.*--DOC_HIDE_START")
+            set(section ON)
+        endif()
+
+        # Pick lines that are not specified to be hidden
+        if((NOT LINE MATCHES "^.*--DOC_[A-Z]+") AND (NOT section))
             set(tmp_output ${tmp_output}\n${DOC_LINE_PREFIX}${line_prefix}${LINE})
         endif()
+
+        # If we found a start marker previously, look for an end marker.
+        # Do this after picking the lines to ensure that lines with
+        # `--DOC_HIDE_END` are omitted
+        if(section AND (LINE MATCHES "^.*--DOC_HIDE_END"))
+            set(section OFF)
+        endif()
     endforeach()
 
     set(${escaped_content} ${tmp_output} PARENT_SCOPE)
diff --git a/tests/examples/awful/tag/module_default_layouts.lua b/tests/examples/awful/tag/module_default_layouts.lua
new file mode 100644
index 000000000..44ac1f39e
--- /dev/null
+++ b/tests/examples/awful/tag/module_default_layouts.lua
@@ -0,0 +1,20 @@
+--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
+tag.emit_signal("request::default_layouts")
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
diff --git a/tests/examples/awful/tag/request_default_layouts.lua b/tests/examples/awful/tag/request_default_layouts.lua
new file mode 100644
index 000000000..87ba30603
--- /dev/null
+++ b/tests/examples/awful/tag/request_default_layouts.lua
@@ -0,0 +1,27 @@
+--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
+tag.emit_signal("request::default_layouts")
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
diff --git a/tests/examples/awful/titlebar/constructor.lua b/tests/examples/awful/titlebar/constructor.lua
new file mode 100644
index 000000000..aabdfde23
--- /dev/null
+++ b/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
diff --git a/tests/examples/wibox/widget/graph/clamp_bars.lua b/tests/examples/wibox/widget/graph/clamp_bars.lua
index c928b9bc9..621fe8ab1 100644
--- a/tests/examples/wibox/widget/graph/clamp_bars.lua
+++ b/tests/examples/wibox/widget/graph/clamp_bars.lua
@@ -50,7 +50,7 @@ end --DOC_HIDE
 parent:add(wibox.layout {--DOC_HIDE
     {--DOC_HIDE
         {--DOC_HIDE
-            markup = "<b>clamp_bars=false</b>",--DOC_HIDE
+            markup = "<b>clamp_bars = false</b>",--DOC_HIDE
             widget = wibox.widget.textbox,--DOC_HIDE
         },--DOC_HIDE
         w_unclamped,--DOC_HIDE
@@ -58,7 +58,7 @@ parent:add(wibox.layout {--DOC_HIDE
     },--DOC_HIDE
     {--DOC_HIDE
         {--DOC_HIDE
-            markup = "<b>clamp_bars=true</b>",--DOC_HIDE
+            markup = "<b>clamp_bars = true</b>",--DOC_HIDE
             widget = wibox.widget.textbox,--DOC_HIDE
         },--DOC_HIDE
         w_clamped,--DOC_HIDE
diff --git a/tests/examples/wibox/widget/graph/nan_color.lua b/tests/examples/wibox/widget/graph/nan_color.lua
index ce9598554..aa8da38f6 100644
--- a/tests/examples/wibox/widget/graph/nan_color.lua
+++ b/tests/examples/wibox/widget/graph/nan_color.lua
@@ -83,7 +83,7 @@ parent:add(wibox.layout {--DOC_HIDE
     },--DOC_HIDE
     {--DOC_HIDE
         {--DOC_HIDE
-            markup = "<b>nan_indication=false</b>",--DOC_HIDE
+            markup = "<b>nan_indication = false</b>",--DOC_HIDE
             widget = wibox.widget.textbox,--DOC_HIDE
         },--DOC_HIDE
         w_false,--DOC_HIDE
diff --git a/tests/examples/wibox/widget/graph/stacked_nan.lua b/tests/examples/wibox/widget/graph/stacked_nan.lua
index 180f5d147..8227f8f5e 100644
--- a/tests/examples/wibox/widget/graph/stacked_nan.lua
+++ b/tests/examples/wibox/widget/graph/stacked_nan.lua
@@ -100,7 +100,7 @@ parent:add(wibox.layout {--DOC_HIDE
     },--DOC_HIDE
     {--DOC_HIDE
         {--DOC_HIDE
-            markup = "<b>nan_indication=false</b>",--DOC_HIDE
+            markup = "<b>nan_indication = false</b>",--DOC_HIDE
             widget = wibox.widget.textbox,--DOC_HIDE
         },--DOC_HIDE
         w_false,--DOC_HIDE