diff --git a/lib/wibox/layout/ratio.lua b/lib/wibox/layout/ratio.lua
index 92983af31..a3a30f822 100644
--- a/lib/wibox/layout/ratio.lua
+++ b/lib/wibox/layout/ratio.lua
@@ -176,6 +176,9 @@ end
 --- Increase the ratio of "widget"
 -- If the increment produce an invalid ratio (not between 0 and 1), the method
 -- do nothing.
+--
+--@DOC_wibox_layout_ratio_inc_ratio_EXAMPLE@
+--
 -- @tparam number index The widget index to change
 -- @tparam number increment An floating point value between -1 and 1 where the
 --   end result is within 0 and 1
@@ -249,7 +252,10 @@ function ratio:set_widget_ratio(widget, percent)
 end
 
 --- Update all widgets to match a set of a ratio.
--- The sum of before, itself and after must be 1 or nothing will be done
+-- The sum of before, itself and after must be 1 or nothing will be done.
+--
+--@DOC_wibox_layout_ratio_ajust_ratio_EXAMPLE@
+--
 -- @tparam number index The index of the widget to change
 -- @tparam number before The sum of the ratio before the widget
 -- @tparam number itself The ratio for "widget"
diff --git a/tests/examples/wibox/layout/ratio/ajust_ratio.lua b/tests/examples/wibox/layout/ratio/ajust_ratio.lua
new file mode 100644
index 000000000..4e18ef8b5
--- /dev/null
+++ b/tests/examples/wibox/layout/ratio/ajust_ratio.lua
@@ -0,0 +1,48 @@
+local generic_widget = ... --DOC_HIDE
+local wibox     = require("wibox") --DOC_HIDE
+local unpack = unpack or table.unpack -- luacheck: globals unpack (compatibility with Lua 5.1) --DOC_HIDE
+
+local first, second, third = generic_widget("first"), --DOC_HIDE
+    generic_widget("second"), generic_widget("third") --DOC_HIDE
+
+local ret = wibox.layout.fixed.vertical()
+
+local function create() --DOC_HIDE
+
+local w = wibox.widget {
+    first,
+    second,
+    third,
+    force_width = 200, --DOC_HIDE
+    layout  = wibox.layout.ratio.horizontal
+}
+
+    return w --DOC_HIDE
+end --DOC_HIDE
+
+local values = {
+    {0.25, 0.50, 0.25},
+    {0.33, 0.55, 0.12},
+    {0.123, 0.456, 0.789},
+    {0.123, 0, 0.789},
+    {0, 1, 0},
+}
+
+for i=1, 5 do
+    ret:add(wibox.widget { --DOC_HIDE
+        markup = "<b>Set " .. i ..":</b>", --DOC_HIDE
+        widget = wibox.widget.textbox --DOC_HIDE
+    }) --DOC_HIDE
+
+    local w = create() --DOC_HIDE
+
+    for _=1, i do --DOC_HIDE
+    w:ajust_ratio(2, unpack(values[i]))
+    end --DOC_HIDE
+
+    ret:add(w) --DOC_HIDE
+end
+
+return ret, 200, 200 --DOC_HIDE
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
diff --git a/tests/examples/wibox/layout/ratio/inc_ratio.lua b/tests/examples/wibox/layout/ratio/inc_ratio.lua
new file mode 100644
index 000000000..f430eab4f
--- /dev/null
+++ b/tests/examples/wibox/layout/ratio/inc_ratio.lua
@@ -0,0 +1,39 @@
+local generic_widget = ... --DOC_HIDE
+local wibox     = require("wibox") --DOC_HIDE
+
+local first, second, third = generic_widget("first"), --DOC_HIDE
+    generic_widget("second"), generic_widget("third") --DOC_HIDE
+
+local ret = wibox.layout.fixed.vertical()
+
+local function create() --DOC_HIDE
+
+local w = wibox.widget {
+    first,
+    second,
+    third,
+    force_width = 200, --DOC_HIDE
+    layout  = wibox.layout.ratio.horizontal
+}
+
+    return w --DOC_HIDE
+end --DOC_HIDE
+
+for i=1, 5 do
+    ret:add(wibox.widget { --DOC_HIDE
+        markup = "<b>Iteration " .. i ..":</b>", --DOC_HIDE
+        widget = wibox.widget.textbox --DOC_HIDE
+    }) --DOC_HIDE
+
+    local w = create() --DOC_HIDE
+
+    for _=1, i do --DOC_HIDE
+    w:inc_ratio(2, 0.1)
+    end --DOC_HIDE
+
+    ret:add(w) --DOC_HIDE
+end
+
+return ret, 200, 200 --DOC_HIDE
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
diff --git a/tests/examples/wibox/layout/ratio/strategy.lua b/tests/examples/wibox/layout/ratio/strategy.lua
new file mode 100644
index 000000000..3079b585e
--- /dev/null
+++ b/tests/examples/wibox/layout/ratio/strategy.lua
@@ -0,0 +1,36 @@
+local generic_widget = ... --DOC_HIDE_ALL
+local wibox     = require("wibox")
+
+local empty_width = wibox.widget {
+    visible = false
+}
+local first, third, fourth = generic_widget("first"), generic_widget("third"), generic_widget("fourth")
+
+local function add(tab, name)
+    table.insert(tab, {
+        markup = "<b>"..name..":</b>",
+        widget = wibox.widget.textbox
+    })
+    table.insert(tab, {
+        first,
+        empty_width,
+        third,
+        fourth,
+        inner_fill_strategy = name,
+        force_width = 200,
+        layout  = wibox.layout.ratio.horizontal
+    })
+end
+
+local ret = {layout = wibox.layout.fixed.vertical}
+add(ret, "default")
+add(ret, "center")
+add(ret, "justify")
+add(ret, "inner_spacing")
+add(ret, "spacing")
+add(ret, "left")
+add(ret, "right")
+
+return wibox.widget(ret), 200, 250
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80