Docs: Naughty - mostly done

Reorganise the config table, so that we have a single table and the
fields are nested.

Signed-off-by: Ignas Anikevicius (gns_ank) <anikevicius@gmail.com>

lib/naughty/core.lua.in

@@ -32,44 +32,56 @@ local tins = table.insert
 local naughty = {}
 
 --- Naughty configuration - a table containing common popup settings.
--- @table naughty.config
-naughty.config = {}
---- Space between popups and edge of the workarea.
--- Default: 4
--- @table naughty.config.padding
-naughty.config.padding = 4
---- Spacing between popups. Default: `1`
--- @table naughty.config.spacing
-naughty.config.spacing = 1
---- List of directories that will be checked by getIcon().
--- Default: `{ "/usr/share/pixmaps/", }`
--- @table naughty.config.icon_dirs
-naughty.config.icon_dirs = { "/usr/share/pixmaps/", }
---- List of formats that will be checked by getIcon().
--- Default: `{ "png", "gif" }`
--- @table naughty.config.icon_formats
-naughty.config.icon_formats = { "png", "gif" }
---- Callback used to modify or reject notifications.
--- Default: `nil`
--- @usage
--- naughty.config.notify_callback = function(args)
---     args.text = 'prefix: ' .. args.text
---     return args
--- end
--- @table naughty.config.notify_callback
-naughty.config.notify_callback = nil
-
-
---- Notification Presets - a table containing presets for different purposes.
--- Preset is a table of any parameters available to notify(), overriding default
--- values (`naughty.config.defaults`)
--- You have to pass a reference of a preset in your notify() call to use the preset
--- The presets "low", "normal" and "critical" are used for notifications over DBUS
 --
--- @field low The preset for notifications with low urgency level
--- @field normal The default preset for every notification without a preset that will also be used for normal urgency level
--- @field critical The preset for notifications with a critical urgency level
--- @table naughty.config.presets
+-- @table naughty.config
+-- @field padding Space between popups and edge of the workarea.
+--   Default: `4`
+-- @field spacing Spacing between popups.
+--   Default: `1`
+-- @field icon_dirs List of directories that will be checked by `getIcon()`.
+--   Default: `{ "/usr/share/pixmaps/", }`
+-- @field icon_formats List of formats that will be checked by `getIcon()`.
+--   Default: `{ "png", "gif" }`
+-- @field notify_callback Callback used to modify or reject notifications.
+--   Default: `nil`
+--    naughty.config.notify_callback = function(args)
+--        args.text = 'prefix: ' .. args.text
+--        return args
+--    end
+--
+-- @field presets Notification Presets - a table containing presets for
+--   different purposes.  Preset is a table of any parameters available to
+--   `notify()`, overriding default values (`naughty.config.defaults`) You have
+--   to pass a reference of a preset in your notify() call to use the preset The
+--   presets `"low"`, `"normal"` and `"critical"` are used for notifications
+--   over DBUS.
+--
+-- @field presets.low The preset for notifications with low urgency level.
+-- @field presets.normal The default preset for every notification without a
+--   preset that will also be used for normal urgency level.
+-- @field presets.critical The preset for notifications with a critical urgency
+--   level.
+--
+-- @field defaults Default values for the params to `notify()`.
+-- These can optionally be overridden by specifying a preset.
+--
+-- @field mapping DBUS notification to preset mapping.
+--   The first element is an object containing the filter If the rules in the
+--   filter matches the associated preset will be applied The rules object can
+--   contain: urgency, category, appname The second element is the preset
+--
+-- @field mapping.1 low urgency
+-- @field mapping.2 normal urgency
+-- @field mapping.3 critical urgency
+--
+naughty.config = {
+    padding = 4,
+    spacing = 1,
+    icon_dirs = { "/usr/share/pixmaps/", },
+    icon_formats = { "png", "gif" },
+    notify_callback = nil,
+}
+
 naughty.config.presets = {
     low = {
         timeout = 5
@@ -82,12 +94,6 @@ naughty.config.presets = {
     }
 }
 
---- Default values for the params to notify().
--- These can optionally be overridden by specifying a preset
---
--- @see naughty.config.presets
--- @see naughty.notify
--- @table naughty.config.defaults
 naughty.config.defaults = {
     timeout = 5,
     text = "",
@@ -260,28 +266,42 @@ function naughty.getById(id)
     end
 end
 
---- Create notification. args is a dictionary of (optional) arguments.
--- @tparam table args The argument table containing any of the arguments bellow.
--- @tparam string args.text Text of the notification. Default: ''
--- @tparam string args.title Title of the notification. Default: nil
--- @tparam int args.timeout Time in seconds after which popup expires.
---   Set 0 for no timeout. Default: 5
--- @tparam int args.hover_timeout Delay in seconds after which hovered popup disappears.
+--- Create notification.
+--
+-- @tab args The argument table containing any of the arguments bellow.
+-- @string args.text Text of the notification.
+--   Default: ''
+-- @string args.title Title of the notification.
 --   Default: nil
--- @tparam int args.screen Target screen for the notification. Default: 1
--- @tparam string args.position Corner of the workarea displaying the popups.
+-- @int args.timeout Time in seconds after which popup expires.
+--   Set 0 for no timeout.
+--   Default: 5
+-- @int args.hover_timeout Delay in seconds after which hovered popup disappears.
+--   Default: nil
+-- @int args.screen Target screen for the notification.
+--   Default: 1
+-- @string args.position Corner of the workarea displaying the popups.
 --   Values: `"top_right"` (default), `"top_left"`, `"bottom_left"`,
 --           `"bottom_right"`, `"top_middle"`, `"bottom_middle"`.
--- @tparam bool args.ontop Boolean forcing popups to display on top. Default: true
--- @tparam int args.height Popup height. Default: nil (auto)
--- @tparam int args.width Popup width. Default: nil (auto)
--- @tparam string args.font Notification font. Default: beautiful.font or awesome.font
--- @tparam string args.icon Path to icon. Default: nil
--- @tparam int args.icon_size Desired icon size in px. Default: nil
--- @tparam string args.fg Foreground color. Default: `beautiful.fg_focus` or `'#ffffff'`
--- @tparam string args.bg Background color. Default: `beautiful.bg_focus` or `'#535d6c'`
--- @tparam int args.border_width Border width. Default: 1
--- @tparam string args.border_color Border color.
+-- @bool args.ontop Boolean forcing popups to display on top.
+--   Default: true
+-- @int args.height Popup height.
+--   Default: nil (auto)
+-- @int args.width Popup width.
+--   Default: nil (auto)
+-- @string args.font Notification font.
+--   Default: beautiful.font or awesome.font
+-- @string args.icon Path to icon.
+--   Default: nil
+-- @int args.icon_size Desired icon size in px.
+--   Default: nil
+-- @string args.fg Foreground color.
+--   Default: `beautiful.fg_focus` or `'#ffffff'`
+-- @string args.bg Background color.
+--   Default: `beautiful.bg_focus` or `'#535d6c'`
+-- @int args.border_width Border width.
+--   Default: 1
+-- @string args.border_color Border color.
 --   Default: `beautiful.border_focus` or `'#535d6c'`
 -- @tparam func args.run Function to run on left click. Default: nil
 -- @tparam func args.destroy Function to run when notification is destroyed. Default: nil.