[doc] add documentation to a few widgets (#8425)

frontend/ui/geometry.lua

@@ -1,5 +1,5 @@
 --[[--
-2D Geometry utilities
+Utilities for 2D geometry.
 
 All of these apply to full rectangles:
 

frontend/ui/widget/confirmbox.lua

@@ -1,5 +1,5 @@
 --[[--
-Widget that shows a confirmation alert with a message and Cancel/OK buttons
+Widget that shows a confirmation alert with a message and Cancel/OK buttons.
 
 Example:
 

frontend/ui/widget/datetimewidget.lua

@@ -1,3 +1,40 @@
+--[[--
+Widget for setting the date or time.
+
+Example for input a time:
+    local DateTimeWidget = require("ui/widget/datetimewidget")
+    local @{gettext|_} = require("gettext")
+
+    local time_widget = DateTimeWidget:new{
+        is_date = false,
+        hour = 10,
+        min = 30,
+        ok_text = _("Set time"),
+        title_text = _("Set time"),
+        callback = function(time)
+            -- use time.hour and time.min here
+        end
+    }
+    UIManager:show(time_widget)
+
+Example for input a date:
+    local DateTimeWidget = require("ui/widget/datetimewidget")
+    local @{gettext|_} = require("gettext")
+
+    local date_widget = DateTimeWidget:new{
+        year = 2021,
+        month = 12,
+        day = 31,
+        ok_text = _("Set date"),
+        title_text = _("Set date"),
+        callback = function(time)
+            -- use time.year, time.month, time.day here
+        end
+    }
+    UIManager:show(date_widget)
+
+--]]--
+
 local Blitbuffer = require("ffi/blitbuffer")
 local ButtonTable = require("ui/widget/buttontable")
 local CenterContainer = require("ui/widget/container/centercontainer")

frontend/ui/widget/imagewidget.lua

@@ -1,5 +1,5 @@
 --[[--
-ImageWidget shows an image from a file or memory
+ImageWidget shows an image from a file or memory.
 
 Show image from file example:
 

frontend/ui/widget/inputdialog.lua

@@ -14,7 +14,7 @@ Example:
         input = "default value",
         -- A placeholder text shown in the text box.
         input_hint = _("Hint text"),
-        input_type = "string",
+        -- input_type = nil, -- default for text
         -- A description shown above the input.
         description = _("Some more description."),
         -- text_type = "password",

frontend/ui/widget/multiinputdialog.lua

@@ -1,3 +1,79 @@
+--[[--
+Widget for taking multiple user inputs.
+
+Example for input of two strings and a number:
+
+    local MultiInputDialog = require("ui/widget/multiinputdialog")
+    local @{ui.uimanager|UIManager} = require("ui/uimanager")
+    local @{gettext|_} = require("gettext")
+
+    local sample_input
+    sample_input = MultiInputDialog:new{
+        title = _("Title to show"),
+        fields = {
+            {
+                description = _("Describe this field"),
+                -- input_type = nil, -- default for text
+                text = _("First input"),
+                hint = _("Name"),
+            },
+            {
+                text = "",
+                hint = _("Address"),
+            },
+            {
+                description = _("Enter a number"),
+                input_type = "number",
+                text = 666,
+                hint = 123,
+            },
+        },
+        buttons = {
+            {
+                {
+                    text = _("Cancel"),
+                    callback = function()
+                        UIManager:close(sample_input)
+                    end
+                },
+                {
+                    text = _("Info"),
+                    callback = function()
+                        -- do something
+                    end
+                },
+                {
+                    text = _("Use settings"),
+                    callback = function(touchmenu_instance)
+                        local fields = MultiInputDialog:getFields()
+                        -- check for user input
+                        if fields[1] ~= "" and fields[2] ~= ""
+                            and fields[3] ~= 0 then
+                            -- insert code here
+                            UIManager:close(sample_input)
+                            -- If we have a touch menu: Update menu entries,
+                            -- when called from a menu
+                            if touchmenu_instance then
+                                touchmenu_instance:updateItems()
+                            end
+                        else
+                            -- not all fields where entered
+                        end
+                    end
+                },
+            },
+        },
+    }
+    UIManager:show(sample_input)
+    sample_input:onShowKeyboard()
+
+
+It is strongly recommended to use a text describing the action to be
+executed, as demonstrated in the example above. If the resulting phrase would be
+longer than three words it should just read "OK".
+--]]--
+
+
 local Blitbuffer = require("ffi/blitbuffer")
 local CenterContainer = require("ui/widget/container/centercontainer")
 local Device = require("device")