diff --git a/objects/client.c b/objects/client.c
index 5a47779f..19ad5f3f 100644
--- a/objects/client.c
+++ b/objects/client.c
@@ -727,6 +727,15 @@ lua_class_t client_class;
 /**
  * The client border width.
  *
+ * When manually set (for example, in `ruled.client` rules), this value
+ * will be static. Otherwise, it is controlled by many `beautiful` variables.
+ *
+ * Be careful, the borders are **around** the geometry, not part of it. If
+ * you want more fancy border, use the `awful.titlebar` API to create
+ * titlebars on each side of the client.
+ *
+ * @DOC_awful_client_border_width_EXAMPLE@
+ *
  * @property border_width
  * @tparam integer border_width
  * @propemits false false
@@ -759,7 +768,7 @@ lua_class_t client_class;
 /**
  * The client border color.
  *
- * @DOC_awful_client_border_width_EXAMPLE@
+ * @DOC_awful_client_border_color_EXAMPLE@
  *
  * Note that setting this directly will override and disable all related theme
  * variables.
@@ -3087,6 +3096,9 @@ luaA_client_kill(lua_State *L)
 }
 
 /** Swap a client with another one in global client list.
+ *
+ * @DOC_sequences_client_swap1_EXAMPLE@
+ *
  * @tparam client c A client to swap with.
  * @method swap
  * @emits swapped
diff --git a/tests/examples/awful/client/border_color.lua b/tests/examples/awful/client/border_color.lua
new file mode 100644
index 00000000..980c9e8c
--- /dev/null
+++ b/tests/examples/awful/client/border_color.lua
@@ -0,0 +1,85 @@
+--DOC_NO_USAGE --DOC_GEN_IMAGE --DOC_ASTERISK
+local awful     = require("awful") --DOC_HIDE
+local wibox     = require("wibox") --DOC_HIDE
+local beautiful = require("beautiful") --DOC_HIDE
+
+screen[1]._resize {width = 480, height = 200} --DOC_HIDE
+
+local wb = awful.wibar { position = "top" }--DOC_HIDE
+
+--DOC_HIDE Create the same number of tags as the default config
+awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.layouts[1]) --DOC_HIDE
+
+--DOC_HIDE Only bother with widgets that are visible by default
+local mykeyboardlayout = awful.widget.keyboardlayout() --DOC_HIDE
+local mytextclock = wibox.widget.textclock() --DOC_HIDE
+local mytaglist = awful.widget.taglist(screen[1], awful.widget.taglist.filter.all, {}) --DOC_HIDE
+local mytasklist = awful.widget.tasklist(screen[1], awful.widget.tasklist.filter.currenttags, {}) --DOC_HIDE
+
+client.connect_signal("request::titlebars", function(c)--DOC_HIDE
+    local top_titlebar = awful.titlebar(c, {--DOC_HIDE
+        height    = 20,--DOC_HIDE
+        bg_normal = beautiful.bg_normal,--DOC_HIDE
+    })--DOC_HIDE
+
+    top_titlebar : setup {--DOC_HIDE
+        { -- Left--DOC_HIDE
+            awful.titlebar.widget.iconwidget(c),--DOC_HIDE
+            layout  = wibox.layout.fixed.horizontal--DOC_HIDE
+        },--DOC_HIDE
+        { -- Middle--DOC_HIDE
+            { -- Title--DOC_HIDE
+                align  = "center",--DOC_HIDE
+                widget = awful.titlebar.widget.titlewidget(c)--DOC_HIDE
+            },--DOC_HIDE
+            layout  = wibox.layout.flex.horizontal--DOC_HIDE
+        },--DOC_HIDE
+        { -- Right--DOC_HIDE
+            awful.titlebar.widget.floatingbutton (c),--DOC_HIDE
+            awful.titlebar.widget.maximizedbutton(c),--DOC_HIDE
+            awful.titlebar.widget.stickybutton   (c),--DOC_HIDE
+            awful.titlebar.widget.ontopbutton    (c),--DOC_HIDE
+            awful.titlebar.widget.closebutton    (c),--DOC_HIDE
+            layout = wibox.layout.fixed.horizontal()--DOC_HIDE
+        },--DOC_HIDE
+        layout = wibox.layout.align.horizontal--DOC_HIDE
+    }--DOC_HIDE
+end)--DOC_HIDE
+
+
+wb:setup { --DOC_HIDE
+    layout = wibox.layout.align.horizontal, --DOC_HIDE
+    { --DOC_HIDE
+        mytaglist, --DOC_HIDE
+        layout = wibox.layout.fixed.horizontal, --DOC_HIDE
+    }, --DOC_HIDE
+    mytasklist, --DOC_HIDE
+    { --DOC_HIDE
+        layout = wibox.layout.fixed.horizontal, --DOC_HIDE
+        mykeyboardlayout, --DOC_HIDE
+        mytextclock, --DOC_HIDE
+    }, --DOC_HIDE
+} --DOC_HIDE
+
+require("gears.timer").run_delayed_calls_now()--DOC_HIDE
+
+local function gen_client(label)--DOC_HIDE
+    local c = client.gen_fake {hide_first=true} --DOC_HIDE
+
+    c:geometry {--DOC_HIDE
+        x      = 105,--DOC_HIDE
+        y      = 60,--DOC_HIDE
+        height = 60,--DOC_HIDE
+        width  = 230,--DOC_HIDE
+    }--DOC_HIDE
+    c._old_geo = {c:geometry()} --DOC_HIDE
+    c:set_label(label) --DOC_HIDE
+    c:emit_signal("request::titlebars")--DOC_HIDE
+    return c --DOC_HIDE
+end --DOC_HIDE
+
+    local c = gen_client("A manually set border_color") --DOC_HIDE
+    c.border_color = "#ff00ff"
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
+
diff --git a/tests/examples/awful/client/border_width.lua b/tests/examples/awful/client/border_width.lua
index 980c9e8c..a711d6d5 100644
--- a/tests/examples/awful/client/border_width.lua
+++ b/tests/examples/awful/client/border_width.lua
@@ -1,85 +1,95 @@
---DOC_NO_USAGE --DOC_GEN_IMAGE --DOC_ASTERISK
-local awful     = require("awful") --DOC_HIDE
-local wibox     = require("wibox") --DOC_HIDE
-local beautiful = require("beautiful") --DOC_HIDE
+--DOC_NO_USAGE --DOC_GEN_IMAGE --DOC_ASTERISK --DOC_HIDE_START
+local awful     = require("awful")
+local wibox     = require("wibox")
+local beautiful = require("beautiful")
 
-screen[1]._resize {width = 480, height = 200} --DOC_HIDE
+screen[1]._resize {width = 480, height = 200}
 
-local wb = awful.wibar { position = "top" }--DOC_HIDE
+local wb = awful.wibar { position = "top" }
 
---DOC_HIDE Create the same number of tags as the default config
-awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.layouts[1]) --DOC_HIDE
+-- Create the same number of tags as the default config
+awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.layouts[1])
 
---DOC_HIDE Only bother with widgets that are visible by default
-local mykeyboardlayout = awful.widget.keyboardlayout() --DOC_HIDE
-local mytextclock = wibox.widget.textclock() --DOC_HIDE
-local mytaglist = awful.widget.taglist(screen[1], awful.widget.taglist.filter.all, {}) --DOC_HIDE
-local mytasklist = awful.widget.tasklist(screen[1], awful.widget.tasklist.filter.currenttags, {}) --DOC_HIDE
+-- Only bother with widgets that are visible by default
+local mykeyboardlayout = awful.widget.keyboardlayout()
+local mytextclock = wibox.widget.textclock()
+local mytaglist = awful.widget.taglist(screen[1], awful.widget.taglist.filter.all, {})
+local mytasklist = awful.widget.tasklist(screen[1], awful.widget.tasklist.filter.currenttags, {})
 
-client.connect_signal("request::titlebars", function(c)--DOC_HIDE
-    local top_titlebar = awful.titlebar(c, {--DOC_HIDE
-        height    = 20,--DOC_HIDE
-        bg_normal = beautiful.bg_normal,--DOC_HIDE
-    })--DOC_HIDE
+client.connect_signal("request::titlebars", function(c)
+    local top_titlebar = awful.titlebar(c, {
+        height    = 20,
+        bg_normal = beautiful.bg_normal,
+    })
 
-    top_titlebar : setup {--DOC_HIDE
-        { -- Left--DOC_HIDE
-            awful.titlebar.widget.iconwidget(c),--DOC_HIDE
-            layout  = wibox.layout.fixed.horizontal--DOC_HIDE
-        },--DOC_HIDE
-        { -- Middle--DOC_HIDE
-            { -- Title--DOC_HIDE
-                align  = "center",--DOC_HIDE
-                widget = awful.titlebar.widget.titlewidget(c)--DOC_HIDE
-            },--DOC_HIDE
-            layout  = wibox.layout.flex.horizontal--DOC_HIDE
-        },--DOC_HIDE
-        { -- Right--DOC_HIDE
-            awful.titlebar.widget.floatingbutton (c),--DOC_HIDE
-            awful.titlebar.widget.maximizedbutton(c),--DOC_HIDE
-            awful.titlebar.widget.stickybutton   (c),--DOC_HIDE
-            awful.titlebar.widget.ontopbutton    (c),--DOC_HIDE
-            awful.titlebar.widget.closebutton    (c),--DOC_HIDE
-            layout = wibox.layout.fixed.horizontal()--DOC_HIDE
-        },--DOC_HIDE
-        layout = wibox.layout.align.horizontal--DOC_HIDE
-    }--DOC_HIDE
-end)--DOC_HIDE
+    top_titlebar : setup {
+        { -- Left
+            awful.titlebar.widget.iconwidget(c),
+            layout  = wibox.layout.fixed.horizontal
+        },
+        { -- Middle
+            { -- Title
+                align  = "center",
+                widget = awful.titlebar.widget.titlewidget(c)
+            },
+            layout  = wibox.layout.flex.horizontal
+        },
+        { -- Right
+            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)
 
 
-wb:setup { --DOC_HIDE
-    layout = wibox.layout.align.horizontal, --DOC_HIDE
-    { --DOC_HIDE
-        mytaglist, --DOC_HIDE
-        layout = wibox.layout.fixed.horizontal, --DOC_HIDE
-    }, --DOC_HIDE
-    mytasklist, --DOC_HIDE
-    { --DOC_HIDE
-        layout = wibox.layout.fixed.horizontal, --DOC_HIDE
-        mykeyboardlayout, --DOC_HIDE
-        mytextclock, --DOC_HIDE
-    }, --DOC_HIDE
-} --DOC_HIDE
+wb:setup {
+    layout = wibox.layout.align.horizontal,
+    {
+        mytaglist,
+        layout = wibox.layout.fixed.horizontal,
+    },
+    mytasklist,
+    {
+        layout = wibox.layout.fixed.horizontal,
+        mykeyboardlayout,
+        mytextclock,
+    },
+}
 
-require("gears.timer").run_delayed_calls_now()--DOC_HIDE
+require("gears.timer").run_delayed_calls_now()
+local counter = 0
 
-local function gen_client(label)--DOC_HIDE
-    local c = client.gen_fake {hide_first=true} --DOC_HIDE
+local function gen_client(label)
+    local c = client.gen_fake {hide_first=true}
 
-    c:geometry {--DOC_HIDE
-        x      = 105,--DOC_HIDE
-        y      = 60,--DOC_HIDE
-        height = 60,--DOC_HIDE
-        width  = 230,--DOC_HIDE
-    }--DOC_HIDE
-    c._old_geo = {c:geometry()} --DOC_HIDE
-    c:set_label(label) --DOC_HIDE
-    c:emit_signal("request::titlebars")--DOC_HIDE
-    return c --DOC_HIDE
-end --DOC_HIDE
+    c:geometry {
+        x      = 45 + counter*1.75,
+        y      = 30 + counter,
+        height = 60,
+        width  = 230,
+    }
+    c._old_geo = {c:geometry()}
+    c:set_label(label)
+    c:emit_signal("request::titlebars")
+    c.border_color = beautiful.bg_highlight
+    counter = counter + 40
 
-    local c = gen_client("A manually set border_color") --DOC_HIDE
-    c.border_color = "#ff00ff"
+    return c
+end
+
+    local c1 = gen_client("Border width: 0")
+    local c2 = gen_client("Border width: 2")
+    local c3 = gen_client("Border width: 10")
+--DOC_HIDE_END
+
+  c1.border_width = 0
+  c2.border_width = 2
+  c3.border_width = 10
 
 --DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80