From a7fd2e2278c3055777bb1960c0bc8df1c6e43fcd Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage Vallee <elv1313@gmail.com>
Date: Sun, 21 Aug 2022 23:02:26 -0700
Subject: [PATCH] naughty.notification: Update the property documentation.

---
 lib/naughty/notification.lua | 138 ++++++++++++++++++++++++-----------
 1 file changed, 94 insertions(+), 44 deletions(-)

diff --git a/lib/naughty/notification.lua b/lib/naughty/notification.lua
index a3da5e5c3..a1c745333 100644
--- a/lib/naughty/notification.lua
+++ b/lib/naughty/notification.lua
@@ -27,6 +27,8 @@ local pcommon = require("awful.permissions._common")
 
 local notification = {}
 
+--luacheck: no max line length
+
 --- Notifications font.
 -- @beautiful beautiful.notification_font
 -- @tparam string|lgi.Pango.FontDescription notification_font
@@ -78,6 +80,8 @@ local notification = {}
 -- notifications.
 -- @property id
 -- @tparam number id
+-- @propertydefault This is autogenerated.
+-- @readonly
 -- @propemits true false
 
 --- Text of the notification.
@@ -92,25 +96,26 @@ local notification = {}
 --- Title of the notification.
 --@DOC_naughty_helloworld_EXAMPLE@
 -- @property title
--- @tparam string title
+-- @tparam[opt=""] string title
 -- @propemits true false
 
 --- Time in seconds after which popup expires.
 --   Set 0 for no timeout.
 -- @property timeout
 -- @tparam number timeout
+-- @propertydefault If unspecified, it can come from either the notification
+--  itself, the presets or the `ruled.notification` rules.
+-- @negativeallowed false
+-- @propertyunit second
 -- @propemits true false
 
 --- The notification urgency level.
 --
--- The default urgency levels are:
---
--- * low
--- * normal
--- * critical
---
 -- @property urgency
--- @tparam string urgency
+-- @tparam[opt="normal"] string urgency
+-- @propertyvalue "low"
+-- @propertyvalue "normal"
+-- @propertyvalue "critical"
 -- @propemits true false
 
 --- The notification category.
@@ -157,7 +162,7 @@ local notification = {}
 -- </table>
 --
 -- @property category
--- @tparam string|nil category
+-- @tparam[opt=nil] string|nil category
 -- @propemits true false
 
 --- True if the notification should be kept when an action is pressed.
@@ -173,29 +178,28 @@ local notification = {}
 --- Delay in seconds after which hovered popup disappears.
 -- @property hover_timeout
 -- @tparam[opt=nil] number|nil hover_timeout
+-- @negativeallowed false
+-- @propertyunit second
 -- @propemits true false
 
 --- Target screen for the notification.
 -- @property screen
--- @tparam screen screen
+-- @tparam[opt=awful.screen.preferred()] screen screen
 -- @propemits true false
 
 --- Corner of the workarea displaying the popups.
 --
--- The possible values are:
---
--- * *top_right*
--- * *top_left*
--- * *bottom_left*
--- * *bottom_right*
--- * *top_middle*
--- * *bottom_middle*
--- * *middle*
---
 --@DOC_awful_notification_box_corner_EXAMPLE@
 --
 -- @property position
--- @tparam[opt=beautiful.notification_position] string position
+-- @tparam[opt=beautiful.notification_position] string|nil position
+-- @propertyvalue "top_right"
+-- @propertyvalue "top_left"
+-- @propertyvalue "bottom_left"
+-- @propertyvalue "bottom_right"
+-- @propertyvalue "top_middle"
+-- @propertyvalue "bottom_middle"
+-- @propertyvalue "middle"
 -- @propemits true false
 -- @see awful.placement.next_to
 
@@ -208,20 +212,26 @@ local notification = {}
 --@DOC_awful_notification_geometry_EXAMPLE@
 --
 -- @property height
--- @tparam number height
+-- @tparam number|nil height
 -- @propemits true false
+-- @propertyunit pixel
+-- @negativeallowed false
+-- @propbeautiful
 -- @see width
 
 --- Popup width.
 -- @property width
--- @tparam number width
+-- @tparam number|nil width
 -- @propemits true false
+-- @propertyunit pixel
+-- @negativeallowed false
+-- @propbeautiful
 -- @see height
 
 --- Notification font.
 --@DOC_naughty_colors_EXAMPLE@
 -- @property font
--- @tparam string font
+-- @tparam[opt=beautiful.notification_font] font|nil font
 -- @propemits true false
 -- @see wibox.widget.textbox.font
 
@@ -242,14 +252,16 @@ local notification = {}
 -- * The `icon` of a client with `dialog` type.
 --
 -- @property icon
--- @tparam string|surface icon
+-- @tparam[opt=nil] image|nil icon
 -- @propemits true false
 -- @see app_icon
 -- @see image
 
 --- Desired icon size in px.
 -- @property icon_size
--- @tparam[opt=beautiful.notification_icon_size] number icon_size
+-- @tparam[opt=beautiful.notification_icon_size] integer|nil icon_size
+-- @negativeallowed false
+-- @propertyunit pixel
 -- @propemits true false
 
 --- The icon provided in the `app_icon` field of the DBus notification.
@@ -258,7 +270,7 @@ local notification = {}
 -- icon name to be fetched from the theme.
 --
 -- @property app_icon
--- @tparam string app_icon
+-- @tparam[opt=nil] string|nil app_icon
 -- @propemits true false
 
 --- The notification image.
@@ -268,7 +280,7 @@ local notification = {}
 -- or stored elsewhere than the filesystem (databases, web, Android phones, etc).
 --
 -- @property image
--- @tparam string|surface image
+-- @tparam[opt=nil] image|nil image
 -- @propemits true false
 
 --- The notification (animated) images.
@@ -279,8 +291,11 @@ local notification = {}
 -- Also note that there is *zero* support for this anywhere else in `naughty`
 -- and very, very few applications support this.
 --
+-- This exists purely to comply with the specification.
+--
 -- @property images
--- @tparam nil|table images
+-- @tparam[opt=nil] nil|table images
+-- @tablerowtype A list of `image`s.
 -- @propemits true false
 
 --- Foreground color.
@@ -288,7 +303,8 @@ local notification = {}
 --@DOC_awful_notification_fg_EXAMPLE@
 --
 -- @property fg
--- @tparam[beautiful.notification_fg] string|color|pattern fg
+-- @tparam[beautiful.notification_fg] color|nil fg
+-- @propbeautiful
 -- @propemits true false
 -- @see title
 -- @see gears.color
@@ -298,22 +314,27 @@ local notification = {}
 --@DOC_awful_notification_bg_EXAMPLE@
 --
 -- @property bg
--- @tparam[opt=beautiful.notification_bg] string|color|pattern bg
+-- @tparam[opt=beautiful.notification_bg] color|nil bg
 -- @propemits true false
 -- @see title
 -- @see gears.color
 
 --- Border width.
 -- @property border_width
--- @tparam[opt=beautiful.notification_border_width or 0] number border_width
+-- @tparam[opt=beautiful.notification_border_width or 0] number|nil border_width
+-- @negativeallowed false
+-- @propertyunit pixel
+-- @propbeautiful
 -- @propemits true false
 
 --- Border color.
 --
 --@DOC_awful_notification_border_color_EXAMPLE@
 --
+-- Please note that only string (like `#ff0000`) are supported.
+--
 -- @property border_color
--- @tparam[opt=beautiful.notification_border_color] string border_color
+-- @tparam[opt=beautiful.notification_border_color] string|nil border_color
 -- @propemits true false
 -- @see gears.color
 
@@ -332,12 +353,15 @@ local notification = {}
 --@DOC_naughty_shape_EXAMPLE@
 --
 -- @property shape
--- @tparam gears.shape shape
+-- @tparam[opt=beautiful.notification_shape] shape|nil shape
 -- @propemits true false
 
 --- Widget opacity.
 -- @property opacity
--- @tparam number opacity Between 0 to 1.
+-- @tparam[opt=beautiful.notification_opacity] number|nil opacity
+-- @rangestart 0.0
+-- @rangestop 1.0
+-- @propertyunit Gradient beween 0.0 (transparent) and 1.0 (opaque).
 -- @propemits true false
 
 --- Widget margin.
@@ -345,7 +369,15 @@ local notification = {}
 --@DOC_awful_notification_margin_EXAMPLE@
 --
 -- @property margin
--- @tparam number|table margin
+-- @tparam[opt=beautiful.notification_margin] number|table|nil margin
+-- @tparam[opt=0] number margin.top
+-- @tparam[opt=0] number margin.bottom
+-- @tparam[opt=0] number margin.left
+-- @tparam[opt=0] number margin.right
+-- @propertytype number A single value for all sides.
+-- @propertytype table A different value for all sides.
+-- @negativeallowed false
+-- @propertyunit pixel
 -- @propemits true false
 -- @see shape
 
@@ -369,14 +401,24 @@ local notification = {}
 -- args will override ones defined
 --   in the preset.
 -- @property preset
--- @tparam table preset
+-- @tparam[opt=nil] table|nil preset
 -- @propemits true false
 
 --- Function that will be called with all arguments.
 --   The notification will only be displayed if the function returns true.
 --   Note: this function is only relevant to notifications sent via dbus.
 -- @property callback
--- @tparam function callback
+-- @tparam[opt=nil] function|nil callback
+-- @functionparam table legacy_data
+-- @functionparam string appname
+-- @functionparam number replaces_id
+-- @functionparam string app_icon
+-- @functionparam string title
+-- @functionparam string message
+-- @functionparam table actions
+-- @functionparam table hints
+-- @functionparam number expire
+-- @functionnoreturn
 -- @propemits true false
 
 --- A table containing strings that represents actions to buttons.
@@ -384,7 +426,8 @@ local notification = {}
 -- The table key (a number) is used by DBus to set map the action.
 --
 -- @property actions
--- @tparam table actions
+-- @tparam[opt={}] table actions
+-- @tablerowtype A list of `naughty.action` objects.
 -- @propemits true false
 
 --- Ignore this notification, do not display.
@@ -408,6 +451,8 @@ local notification = {}
 -- @property is_expired
 -- @tparam boolean is_expired
 -- @propemits true false
+-- @propertydefault This becomes `true` either then `:destroy()` is called or
+--  if the `timeout` expires.
 -- @see naughty.expiration_paused
 
 --- If the timeout needs to be reset when a property changes.
@@ -438,7 +483,8 @@ local notification = {}
 -- client.
 --
 -- @property clients
--- @tparam table clients
+-- @tparam[opt={}] table clients
+-- @tablerowtype A list of `client` objects.
 
 --- The maximum popup width.
 --
@@ -447,8 +493,11 @@ local notification = {}
 -- decision to the layout.
 --
 -- @property max_width
--- @tparam[opt=500] number max_width
+-- @tparam[opt=500] number|nil max_width
+-- @propertyunit pixel
+-- @negativeallowed false
 -- @propemits true false
+-- @propbeautiful
 
 --- The application name specified by the notification.
 --
@@ -456,7 +505,7 @@ local notification = {}
 -- property, but can sometime be specified for remote or headless notifications.
 -- In these case, it helps to triage and detect the notification from the rules.
 -- @property app_name
--- @tparam string app_name
+-- @tparam[opt=nil] string|nil app_name
 -- @propemits true false
 
 --- The widget template used to represent the notification.
@@ -465,7 +514,8 @@ local notification = {}
 -- off with a specialized notification widget.
 --
 -- @property widget_template
--- @tparam table|nil widget_template
+-- @tparam[opt=nil] template|nil widget_template
+-- @propertydefault The default template as the icon, title, message and actions.
 -- @propemits true false
 
 --- Destroy notification by notification object.
@@ -919,7 +969,7 @@ end
 -- @tparam[opt=`beautiful.notification_height` or auto] integer args.height Popup height.
 -- @tparam[opt=`beautiful.notification_width` or auto] integer args.width Popup width.
 -- @tparam[opt=`beautiful.notification_font` or `beautiful.font` or `awesome.font`] string|lgi.Pango.FontDescription args.font Notification font.
--- @tparam[opt] gears.surface args.icon Path to icon.
+-- @tparam[opt] image args.icon Path to icon.
 -- @tparam[opt] integer args.icon_size Desired icon size in px.
 -- @tparam[opt=`beautiful.notification_fg` or `beautiful.fg_focus` or `'#ffffff'`] string args.fg Foreground color.
 -- @tparam[opt=`beautiful.notification_fg` or `beautiful.bg_focus` or `'#535d6c'`] string args.bg Background color.