diff --git a/lib/gears/cache.lua b/lib/gears/cache.lua
index 9fb1d908..1be1d8f4 100644
--- a/lib/gears/cache.lua
+++ b/lib/gears/cache.lua
@@ -1,4 +1,16 @@
 ---------------------------------------------------------------------------
+--- Cache object with data that can be garbage-collected.
+--
+-- Here is an example with a basic cache:
+--
+--@DOC_text_gears_cache_cache_EXAMPLE@
+--
+-- The example below demonstrates how the garbage collector will clear the
+-- cache:
+--
+--@DOC_text_gears_cache_another_cache_EXAMPLE@
+--
+--
 -- @author Uli Schlachter
 -- @copyright 2015 Uli Schlachter
 -- @classmod gears.cache
diff --git a/tests/examples/text/gears/cache/another_cache.lua b/tests/examples/text/gears/cache/another_cache.lua
new file mode 100644
index 00000000..db260fe2
--- /dev/null
+++ b/tests/examples/text/gears/cache/another_cache.lua
@@ -0,0 +1,21 @@
+--DOC_GEN_OUTPUT --DOC_HIDE
+local gears = require("gears") --DOC_HIDE
+
+local function tostring_for_cache(obj)
+    return obj[1]
+end
+local counter = 0
+local wrapper_cache = gears.cache.new(function(arg)
+    local kind = "cache object #" .. tostring(counter) .. " for " .. tostring(arg)
+    counter = counter + 1
+    return setmetatable({ kind }, { __tostring = tostring_for_cache })
+end)
+print(wrapper_cache:get("first"))
+print(wrapper_cache:get("second"))
+-- No new object since it already exists
+print(wrapper_cache:get("first"))
+print("forcing a garbage collect")
+-- The GC can *always* clear the cache
+collectgarbage("collect")
+print(wrapper_cache:get("first"))
+print(wrapper_cache:get("second"))
diff --git a/tests/examples/text/gears/cache/another_cache.output.txt b/tests/examples/text/gears/cache/another_cache.output.txt
new file mode 100644
index 00000000..d932c681
--- /dev/null
+++ b/tests/examples/text/gears/cache/another_cache.output.txt
@@ -0,0 +1,6 @@
+cache object #0 for first
+cache object #1 for second
+cache object #0 for first
+forcing a garbage collect
+cache object #2 for first
+cache object #3 for second
diff --git a/tests/examples/text/gears/cache/cache.lua b/tests/examples/text/gears/cache/cache.lua
new file mode 100644
index 00000000..d5326f52
--- /dev/null
+++ b/tests/examples/text/gears/cache/cache.lua
@@ -0,0 +1,14 @@
+--DOC_GEN_OUTPUT --DOC_HIDE
+local cache = require("gears.cache") --DOC_HIDE
+local test_cache = cache.new(function(test)
+    -- let's just print about what we created
+    print("new entry created with value " .. test)
+    -- Pretend this is some expensive computation
+    return test * 42
+end)
+-- Populate the cache
+print(test_cache:get(0))
+print(test_cache:get(1))
+print(test_cache:get(2))
+-- no message since it exists
+print(test_cache:get(0))
diff --git a/tests/examples/text/gears/cache/cache.output.txt b/tests/examples/text/gears/cache/cache.output.txt
new file mode 100644
index 00000000..873bc078
--- /dev/null
+++ b/tests/examples/text/gears/cache/cache.output.txt
@@ -0,0 +1,7 @@
+new entry created with value 0
+0
+new entry created with value 1
+42
+new entry created with value 2
+84
+0