doc(w.w.textbox): Improve ellipsize documentation

The list of possible values was missing one. Additionally, this adds an
example to visualize the available options.

Signed-off-by: Lucas Schwiderski <lucas@lschwiderski.de>

lib/wibox/widget/textbox.lua

@@ -222,17 +222,22 @@ function textbox:get_text()
     return self._private.layout.text
 end
 
---- Set a textbox ellipsize mode.
+--- Set the text ellipsize mode.
 --
 -- Valid values are:
 --
--- * **start**
+-- * `"start"`
--- * **middle**
+-- * `"middle"`
--- * **end**
+-- * `"end"`
+-- * `"none"`
+--
+-- See Pango for additional details:
+-- [Layout.set_ellipsize](https://docs.gtk.org/Pango/method.Layout.set_ellipsize.html)
+--
+--@DOC_wibox_widget_textbox_ellipsize_EXAMPLE@
 --
 -- @property ellipsize
--- @tparam string mode Where should long lines be shortened? "start", "middle"
+-- @tparam string mode The ellipsize mode.
---  or "end".
 -- @propemits true false
 
 function textbox:set_ellipsize(mode)

tests/examples/wibox/widget/textbox/ellipsize.lua

@@ -0,0 +1,59 @@
+--DOC_GEN_IMAGE --DOC_HIDE
+
+--DOC_HIDE_START
+local parent = ...
+local wibox  = require("wibox")
+
+local widget = function(inner)
+    return wibox.widget {
+        {
+            {
+                inner,
+                margins = 5,
+                widget = wibox.container.margin,
+            },
+            border_width = 2,
+            widget = wibox.container.background,
+        },
+        strategy = "max",
+        height = 25,
+        widget = wibox.container.constraint,
+    }
+end
+
+local widgets = {
+--DOC_HIDE_END
+
+widget{
+    text = "This is a very long text, that cannot be displayed fully.",
+    ellipsize = "start",
+    widget = wibox.widget.textbox,
+},
+
+widget{
+    text = "This is a very long text, that cannot be displayed fully.",
+    ellipsize = "end",
+    widget = wibox.widget.textbox,
+},
+
+widget{
+    text = "This is a very long text, that cannot be displayed fully.",
+    ellipsize = "middle",
+    widget = wibox.widget.textbox,
+},
+
+widget{
+    text = "This is a very long text, that cannot be displayed fully.",
+    ellipsize = "none",
+    valign = "top",
+    widget = wibox.widget.textbox,
+}
+
+--DOC_HIDE_START
+}
+
+parent:set_children(widgets)
+
+return parent:fit({ dpi = 96 }, 150, 200)
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80