diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua
index 2e3c3f1b7..94bd600d0 100644
--- a/lib/awful/tag.lua
+++ b/lib/awful/tag.lua
@@ -713,6 +713,8 @@ end
 -- See the layout suit documentation for information about how the master width
 -- factor is used.
 --
+-- @DOC_screen_mwfact_EXAMPLE@
+--
 -- **Signal:**
 --
 -- * *property::mwfact* (deprecated)
@@ -1088,9 +1090,17 @@ end
 
 --- The gap (spacing, also called `useless_gap`) between clients.
 --
--- This property allow to waste space on the screen in the name of style,
+-- This property allows to waste space on the screen in the name of style,
 -- unicorns and readability.
 --
+-- In this example, the value of `gap` is set to 20:
+--
+-- @DOC_screen_gaps_EXAMPLE@
+--
+-- Compared to setting to the (very high) value of 50:
+--
+-- @DOC_screen_gaps2_EXAMPLE@
+--
 -- **Signal:**
 --
 -- * *property::useless_gap*
@@ -1141,6 +1151,19 @@ end
 
 --- Enable gaps for a single client.
 --
+-- If the gaps are used purely for readability when multiple
+-- clients are tiled, then it may make sense to disable it
+-- when there is only a single client (to recover that space).
+-- In that case, set `gap_single_client` to `false`.
+--
+-- Default (with a 20px gap):
+--
+-- @DOC_screen_gap_single_client_true_EXAMPLE@
+--
+-- when set to false:
+--
+-- @DOC_screen_gap_single_client_false_EXAMPLE@
+--
 -- **Signal:**
 --
 -- * *property::gap\_single\_client*
diff --git a/tests/examples/screen/gap_single_client_false.lua b/tests/examples/screen/gap_single_client_false.lua
new file mode 100644
index 000000000..fd09a79ee
--- /dev/null
+++ b/tests/examples/screen/gap_single_client_false.lua
@@ -0,0 +1,42 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL
+
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+local awful = {
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.tile")
+}
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen            = screen[1],
+    selected          = true,
+    layout            = awful.tag_layout.right,
+    gap               = 20,
+    gap_single_client = false,
+})
+
+local clients = {
+    ['client #1'] = client.gen_fake{},
+}
+
+return {
+    factor                = 2    ,
+    show_boxes            = true,
+    draw_wibar            = wibar,
+    draw_clients          = clients,
+    display_screen_info   = false,
+    draw_gaps             = true,
+}
diff --git a/tests/examples/screen/gap_single_client_true.lua b/tests/examples/screen/gap_single_client_true.lua
new file mode 100644
index 000000000..53a75434c
--- /dev/null
+++ b/tests/examples/screen/gap_single_client_true.lua
@@ -0,0 +1,42 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL
+
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+local awful = {
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.tile")
+}
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen            = screen[1],
+    selected          = true,
+    layout            = awful.tag_layout.right,
+    gap               = 20,
+    gap_single_client = true, -- its the default
+})
+
+local clients = {
+    ['client #1'] = client.gen_fake{},
+}
+
+return {
+    factor                = 2    ,
+    show_boxes            = true,
+    draw_wibar            = wibar,
+    draw_clients          = clients,
+    display_screen_info   = false,
+    draw_gaps             = true,
+}
diff --git a/tests/examples/screen/gaps.lua b/tests/examples/screen/gaps.lua
new file mode 100644
index 000000000..d8f358ca4
--- /dev/null
+++ b/tests/examples/screen/gaps.lua
@@ -0,0 +1,43 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL
+
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+local awful = {
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.tile")
+}
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen   = screen[1],
+    selected = true,
+    layout   = awful.tag_layout.right,
+    gap      = 20
+})
+
+local clients = {
+    ['client #1'] = client.gen_fake{},
+    ['client #2'] = client.gen_fake{},
+    ['client #3'] = client.gen_fake{}
+}
+
+return {
+    factor                = 2    ,
+    show_boxes            = true,
+    draw_wibar            = wibar,
+    draw_clients          = clients,
+    display_screen_info   = false,
+    draw_gaps             = true,
+}
diff --git a/tests/examples/screen/gaps2.lua b/tests/examples/screen/gaps2.lua
new file mode 100644
index 000000000..544c5833b
--- /dev/null
+++ b/tests/examples/screen/gaps2.lua
@@ -0,0 +1,43 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL
+
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+local awful = {
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.tile")
+}
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen   = screen[1],
+    selected = true,
+    layout   = awful.tag_layout.right,
+    gap      = 50
+})
+
+local clients = {
+    ['client #1'] = client.gen_fake{},
+    ['client #2'] = client.gen_fake{},
+    ['client #3'] = client.gen_fake{}
+}
+
+return {
+    factor                = 2    ,
+    show_boxes            = true,
+    draw_wibar            = wibar,
+    draw_clients          = clients,
+    display_screen_info   = false,
+    draw_gaps             = true,
+}
diff --git a/tests/examples/screen/mwfact.lua b/tests/examples/screen/mwfact.lua
new file mode 100644
index 000000000..10767a4e3
--- /dev/null
+++ b/tests/examples/screen/mwfact.lua
@@ -0,0 +1,55 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL
+
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+
+local awful = {
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.tile")
+}
+
+function awful.spawn(_, args)
+    local c = client.gen_fake{}
+    c:tags({args.tag})
+    assert(#c:tags() == 1)
+    assert(c:tags()[1] == args.tag)
+end
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen              = screen[1],
+    selected            = true,
+    layout              = awful.tag_layout.right,
+    gap                 = 5,
+    master_width_factor = 0.66
+})
+
+local clients = {
+    ['master #1 (66%)'] = client.gen_fake{},
+    ['slave  #1 (33%)'] = client.gen_fake{},
+    ['slave  #2 (33%)'] = client.gen_fake{}
+}
+for _,c in ipairs(clients) do
+    c:tags{"1"}
+end
+
+return {
+    factor                = 2    ,
+    show_boxes            = true,
+    draw_wibar            = wibar,
+    draw_clients          = clients,
+    display_screen_info   = false,
+    draw_mwfact           = true,
+}