From 4fa957b75dfabe63d3eb4636b5e409038318b461 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 10 Jul 2022 00:29:33 -0700 Subject: [PATCH] doc: Force all properties to document their default value. --- docs/config.ld | 31 +++++++++++++++++++++++++++++++ lib/wibox/widget/imagebox.lua | 18 +++++++++--------- lib/wibox/widget/piechart.lua | 2 +- lib/wibox/widget/progressbar.lua | 2 +- lib/wibox/widget/separator.lua | 2 +- lib/wibox/widget/systray.lua | 8 ++++---- lib/wibox/widget/textbox.lua | 4 ++-- lib/wibox/widget/textclock.lua | 6 +++--- 8 files changed, 52 insertions(+), 21 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index 56a3efe3e..7b6d684af 100644 --- a/docs/config.ld +++ b/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=`. + print( + "WARNING: Property", item.name .." from "..item.module.name --, + --"doesn't have a default value. Add `[opt=value]` to the @tparam" + ) + end + end end } diff --git a/lib/wibox/widget/imagebox.lua b/lib/wibox/widget/imagebox.lua index 946bddc38..6473ef9c9 100644 --- a/lib/wibox/widget/imagebox.lua +++ b/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 diff --git a/lib/wibox/widget/piechart.lua b/lib/wibox/widget/piechart.lua index 1268a6ba0..0642ead31 100644 --- a/lib/wibox/widget/piechart.lua +++ b/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 diff --git a/lib/wibox/widget/progressbar.lua b/lib/wibox/widget/progressbar.lua index c541d4ecd..be64eabd1 100644 --- a/lib/wibox/widget/progressbar.lua +++ b/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 diff --git a/lib/wibox/widget/separator.lua b/lib/wibox/widget/separator.lua index d600bcd5c..aff0c99f9 100644 --- a/lib/wibox/widget/separator.lua +++ b/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. diff --git a/lib/wibox/widget/systray.lua b/lib/wibox/widget/systray.lua index 911c768d4..37d7596c1 100644 --- a/lib/wibox/widget/systray.lua +++ b/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) diff --git a/lib/wibox/widget/textbox.lua b/lib/wibox/widget/textbox.lua index be8f2d36b..8996b21c4 100644 --- a/lib/wibox/widget/textbox.lua +++ b/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. -- `bold`). 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 diff --git a/lib/wibox/widget/textclock.lua b/lib/wibox/widget/textclock.lua index 6d3776831..13fe21fa9 100644 --- a/lib/wibox/widget/textclock.lua +++ b/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