doc: Force all properties to document their default value.

docs/config.ld

@@ -234,6 +234,37 @@ create_type {
                 " doesn't match the property name. For linting purpose, please fix this."
             )
         end
+
+        -- Properties should have a default value. If they don't or if the
+        -- default depends on the context, then `opt=nil` should be used to
+        -- mute this warning.
+        if not item:default_of_param(item.params[1]) then
+            local auto_opt = nil
+
+            -- Extract the default value from other metadata.
+            if item.tags["propbeautiful"] and item.tags["propbeautiful"][1] then
+                auto_opt = "beautiful."..(item.module.name.."_"..item.name):gsub("[.]", "_")
+            elseif item.tags["usebeautiful"] and item.tags["usebeautiful"][1] then
+                auto_opt = item.tags["usebeautiful"][1]:match("[^ ]+")
+            end
+
+            -- This adds a default value. It works for LDoc 1.4.5, but is a
+            -- private API and might break in the future.
+            if auto_opt then
+                local mods = item.modifiers[item.parameter]
+
+                if mods then
+                    mods[item.params[1]].opt = auto_opt
+                end
+            else
+                -- The default could not be determined automatically, it requires
+                -- an explicit `opt=<value>`.
+                print(
+                    "WARNING: Property", item.name .." from "..item.module.name --,
+                    --"doesn't have a default value. Add `[opt=value]` to the @tparam"
+                )
+            end
+        end
     end
 }
 

lib/wibox/widget/imagebox.lua

@@ -304,7 +304,7 @@ end
 -- * `nil`: Unset the image.
 --
 -- @property image
--- @tparam image image The image to render.
+-- @tparam[opt=nil] image image The image to render.
 -- @propemits false false
 
 --- Set the `imagebox` image.
@@ -370,7 +370,7 @@ end
 -- @DOC_wibox_widget_imagebox_clip_shape_EXAMPLE@
 --
 -- @property clip_shape
--- @tparam function|gears.shape clip_shape A `gears.shape` compatible shape function.
+-- @tparam[opt=nil] function|gears.shape clip_shape A `gears.shape` compatible shape function.
 -- @propemits true false
 -- @see gears.shape
 
@@ -402,7 +402,7 @@ end
 -- @DOC_wibox_widget_imagebox_resize_EXAMPLE@
 -- @property resize
 -- @propemits true false
--- @tparam boolean resize
+-- @tparam[opt=true] boolean resize
 
 --- Allow the image to be upscaled (made bigger).
 --
@@ -412,7 +412,7 @@ end
 --
 -- @DOC_wibox_widget_imagebox_upscale_EXAMPLE@
 -- @property upscale
--- @tparam boolean upscale
+-- @tparam[opt=self.resize] boolean upscale
 -- @see downscale
 -- @see resize
 
@@ -424,7 +424,7 @@ end
 --
 -- @DOC_wibox_widget_imagebox_downscale_EXAMPLE@
 -- @property downscale
--- @tparam boolean downscale
+-- @tparam[opt=self.resize] boolean downscale
 -- @see upscale
 -- @see resize
 
@@ -439,7 +439,7 @@ end
 --@DOC_wibox_widget_imagebox_stylesheet_EXAMPLE@
 --
 -- @property stylesheet
--- @tparam string stylesheet
+-- @tparam[opt=""] string stylesheet
 -- @propemits true false
 
 --- Set the SVG DPI (dot per inch).
@@ -455,7 +455,7 @@ end
 --@DOC_wibox_widget_imagebox_dpi_EXAMPLE@
 --
 -- @property dpi
--- @tparam number|table dpi
+-- @tparam[opt=96] number|table dpi
 -- @propemits true false
 -- @see auto_dpi
 
@@ -597,7 +597,7 @@ end
 -- @DOC_wibox_widget_imagebox_max_scaling_factor_EXAMPLE@
 --
 -- @property max_scaling_factor
--- @tparam number max_scaling_factor
+-- @tparam[opt=0] number max_scaling_factor Use `0` for "no limit".
 -- @propemits true false
 -- @see valign
 -- @see halign
@@ -629,7 +629,7 @@ end
 -- @DOC_wibox_widget_imagebox_scaling_quality_EXAMPLE@
 --
 -- @property scaling_quality
--- @tparam string scaling_quality Either `"fast"`, `"good"`, `"best"`,
+-- @tparam[op="fast"] string scaling_quality Either `"fast"`, `"good"`, `"best"`,
 --   `"nearest"` or `"bilinear"`.
 -- @propemits true false
 -- @see resize

lib/wibox/widget/piechart.lua

@@ -140,7 +140,7 @@ end
 --- The pie chart data list.
 --
 -- @property data_list
--- @tparam table data_list Sorted table where each entry has a label as its
+-- @tparam[opt={}] table data_list Sorted table where each entry has a label as its
 -- first value and a number as its second value.
 -- @propemits false false
 

lib/wibox/widget/progressbar.lua

@@ -519,7 +519,7 @@ end
 -- @DOC_wibox_widget_progressbar_value_EXAMPLE@
 --
 -- @property value
--- @tparam number value The progress bar value.
+-- @tparam[opt=0] number value The progress bar value.
 -- @propemits true false
 -- @see max_value
 

lib/wibox/widget/separator.lua

@@ -43,7 +43,7 @@ local separator = {}
 --@DOC_wibox_widget_separator_orientation_EXAMPLE@
 --
 -- @property orientation
--- @tparam string orientation
+-- @tparam[opt="auto"] string orientation
 -- @propemits true false
 
 --- The separator's thickness.

lib/wibox/widget/systray.lua

@@ -148,7 +148,7 @@ end
 -- available space. Otherwise, any single icon has a size of `size`x`size`.
 --
 -- @property base_size
--- @tparam integer|nil base_size The base size
+-- @tparam[opt=nil] integer|nil base_size The base size
 -- @propemits true false
 
 function systray:set_base_size(size)
@@ -162,7 +162,7 @@ end
 --- Decide between horizontal or vertical display.
 --
 -- @property horizontal
--- @tparam boolean horizontal Use horizontal mode?
+-- @tparam[opt=true] boolean horizontal Use horizontal mode?
 -- @propemits true false
 
 function systray:set_horizontal(horiz)
@@ -176,7 +176,7 @@ end
 --- Should the systray icons be displayed in reverse order?
 --
 -- @property reverse
--- @tparam boolean reverse Display in reverse order.
+-- @tparam[opt=false] boolean reverse Display in reverse order.
 -- @propemits true false
 
 function systray:set_reverse(rev)
@@ -194,7 +194,7 @@ end
 -- visible on the primary screen. The default value is "primary".
 --
 -- @property screen
--- @tparam screen|"primary" screen The screen to display on.
+-- @tparam[opt=nil] screen|"primary" screen The screen to display on.
 -- @propemits true false
 
 function systray:set_screen(s)

lib/wibox/widget/textbox.lua

@@ -189,7 +189,7 @@ end
 -- @DOC_wibox_widget_textbox_markup2_EXAMPLE@
 --
 -- @property markup
--- @tparam string markup The text to set. This can contain pango markup (e.g.
+-- @tparam[opt=self.text] string markup The text to set. This can contain pango markup (e.g.
 --   `<b>bold</b>`). You can use `gears.string.escape` to escape
 --   parts of it.
 -- @propemits true false
@@ -217,7 +217,7 @@ end
 -- @DOC_wibox_widget_textbox_text2_EXAMPLE@
 --
 -- @property text
--- @tparam string text The text to display. Pango markup is ignored and shown
+-- @tparam[opt=""] string text The text to display. Pango markup is ignored and shown
 --  as-is.
 -- @propemits true false
 -- @see markup

lib/wibox/widget/textclock.lua

@@ -70,7 +70,7 @@ end
 -- For information about the format specifiers, see
 -- [the GLib docs](https://developer.gnome.org/glib/stable/glib-GDateTime.html#g-date-time-format).
 -- @property format
--- @tparam string format The new time format. This can contain pango markup.
+-- @tparam[opt=" %a %b %d %H:%M"] string format The new time format. This can contain pango markup.
 
 function textclock:set_format(format)
     self._private.format = format
@@ -86,7 +86,7 @@ end
 -- e.g. "Z" for UTC, "±hh:mm" or "Europe/Amsterdam". See
 -- [GTimeZone](https://developer.gnome.org/glib/stable/glib-GTimeZone.html#g-time-zone-new).
 -- @property timezone
--- @tparam string timezone
+-- @tparam[opt=TimeZone.new()] string timezone
 
 function textclock:set_timezone(tzid)
     self._private.tzid = tzid
@@ -101,7 +101,7 @@ end
 --- Set the clock's refresh rate.
 --
 -- @property refresh
--- @tparam number refresh How often the clock is updated, in seconds
+-- @tparam[opt=60] number refresh How often the clock is updated, in seconds
 
 function textclock:set_refresh(refresh)
     self._private.refresh = refresh or self._private.refresh