From 45a458a2b74b3a039b088234dc42d37d71e6e9dd Mon Sep 17 00:00:00 2001
From: Aire-One <aireone@aireone.xyz>
Date: Fri, 12 Nov 2021 16:02:24 +0100
Subject: [PATCH] doc(w.w.template) module description

---
 lib/wibox/widget/template.lua                 | 19 +++++++++++-
 .../wibox/widget/template/basic_textbox.lua   | 31 +++++++++++++++++++
 .../template/basic_textbox_declarative.lua    | 25 +++++++++++++++
 3 files changed, 74 insertions(+), 1 deletion(-)
 create mode 100644 tests/examples/wibox/widget/template/basic_textbox.lua
 create mode 100644 tests/examples/wibox/widget/template/basic_textbox_declarative.lua

diff --git a/lib/wibox/widget/template.lua b/lib/wibox/widget/template.lua
index 8bf2a1d6d..71ee7df7d 100644
--- a/lib/wibox/widget/template.lua
+++ b/lib/wibox/widget/template.lua
@@ -5,10 +5,27 @@
 -- concrete widget definition. The template widget can be used to build widgets
 -- that the user can customize at their will, thanks to the template mechanism.
 --
+-- Common usage examples
+-- =====================
+--
+-- A basic implementation of the template widget needs a widget definition and
+-- a callback to manage widget updates.
+--
+-- The `:update()` can be called later to update the widget template. Arguments
+-- can be provided to the `:update()` method, it will be forwarded to the
+-- `update_callback` function.
+--
+--@DOC_wibox_widget_template_basic_textbox_EXAMPLE@
+--
+-- Alternatively, you can declare the `template` widget instance using the
+-- declarative pattern (both variants are strictly equivalent):
+--
+--@DOC_wibox_widget_template_basic_textbox_declarative_EXAMPLE@
+--
 -- @author Aire-One
 -- @copyright 2021 Aire-One <aireone@aireone.xyz>
 --
--- @classmod wibox.widget.template
+-- @widgetmod wibox.widget.template
 -- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
diff --git a/tests/examples/wibox/widget/template/basic_textbox.lua b/tests/examples/wibox/widget/template/basic_textbox.lua
new file mode 100644
index 000000000..a9c2b574c
--- /dev/null
+++ b/tests/examples/wibox/widget/template/basic_textbox.lua
@@ -0,0 +1,31 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE
+
+--DOC_HIDE_START
+local parent = ...
+local wibox = require("wibox")
+--DOC_HIDE_END
+
+    local my_template_widget = wibox.widget.template {
+        template = wibox.widget.textbox,
+        update_callback = function(template_widget, args)
+            local text = args.text or "???"
+            template_widget.widget.text = text
+        end,
+    }
+
+--DOC_NEWLINE
+    -- Later in the code
+
+--DOC_NEWLINE
+    -- With no arguments, the update_callback will fallback to "???"
+    my_template_widget:update()
+
+--DOC_NEWLINE
+    -- With custom arguments, the update_callback will changes the displayed text
+    my_template_widget:update { text = "Cool text to update the template!" }
+
+--DOC_HIDE_START
+
+parent:add(my_template_widget)
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
diff --git a/tests/examples/wibox/widget/template/basic_textbox_declarative.lua b/tests/examples/wibox/widget/template/basic_textbox_declarative.lua
new file mode 100644
index 000000000..9dad45fff
--- /dev/null
+++ b/tests/examples/wibox/widget/template/basic_textbox_declarative.lua
@@ -0,0 +1,25 @@
+--DOC_NO_USAGE
+
+--DOC_HIDE_START
+local wibox = require("wibox")
+--DOC_HIDE_END
+
+    local my_template_widget = {
+        id = "mytemplatewidget",
+        template = wibox.widget.textbox,
+        update_callback = function(template_widget, args)
+            local text = args.text or "???"
+            template_widget.widget.text = text
+        end,
+        widget = wibox.widget.template,
+    }
+
+--DOC_HIDE_START
+
+-- Generate the widget to use the update method in the example.
+-- A better approch would have been to use an ID and the `get_children_by_id`
+-- on the parent.
+local widget = wibox.widget(my_template_widget)
+widget:update { text = "Cool text to update the template!" }
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80