Merge pull request #3676 from Elv13/v44_doc_polishing

Implement documentation linting.

CMakeLists.txt

@@ -292,7 +292,7 @@ if(GENERATE_DOC)
     configure_file(${SOURCE_DIR}/docs/ldoc.ltp ${BUILD_DIR}/docs COPYONLY)
 
     add_custom_target(ldoc ALL
-        DEPENDS ${BUILD_DIR}/doc/index.html
+        DEPENDS ${BUILD_DIR}/doc/index.html DOC_EXAMPLES_PPOSTPROCESS_CLEANUP
     )
 
     if (STRICT_TESTS)

build-utils/check_for_invalid_requires.lua

@@ -62,7 +62,10 @@ local allowed_deps = {
         naughty = true,
     },
     -- TODO: Get rid of these
-    ["gears.surface"]        = { ["wibox.hierarchy"] = true },
+    ["gears.surface"]        = {
+        ["wibox.hierarchy"] = true,
+        beautiful = true,
+    },
 }
 
 -- Turn "foo.bar.baz" into "foo.bar". Returns nil if there is nothing more to

dbus.c

@@ -19,7 +19,14 @@
  *
  */
 
-/** awesome D-Bus API
+/** A deprecated low-level D-Bus API **DO NOT USE**.
+ *
+ * `lgi.GDBus` is always better. This module will eventually be removed.
+ * If it ever breaks due to an upstream API change, it wont be fixed.
+ *
+ * It still exists for compatibility reasons since some user have used it
+ * in the past.
+ *
  * @author Julien Danjou <julien@danjou.info>
  * @copyright 2008-2009 Julien Danjou
  * @module dbus
@@ -798,10 +805,10 @@ luaA_dbus_disconnect_signal(lua_State *L)
  * @param path A string with the dbus path.
  * @param interface A string with the dbus interface.
  * @param method A string with the dbus method name.
- * @param type_1st_arg type of 1st argument
- * @param value_1st_arg value of 1st argument
- * @param type_2nd_arg type of 2nd argument
- * @param value_2nd_arg value of 2nd argument
+ * @param type_1st_arg Type of 1st argument
+ * @param value_1st_arg Value of 1st argument
+ * @param type_2nd_arg Type of 2nd argument
+ * @param value_2nd_arg Value of 2nd argument
  * ... etc
  * @function emit_signal
  */

docs/05-awesomerc.md.lua

@@ -324,6 +324,8 @@ rc_lua:close()
 
 
 table.insert(output_script, "-- @script rc.lua")
+table.insert(output_script, "-- @usebeautiful beautiful.awesome_icon")
+table.insert(output_script, "-- @usebeautiful beautiful.wallpaper")
 
 rc_script = assert(io.open(rc_script, "w"))
 rc_script:write(table.concat(output_script, "\n"))

docs/89-NEWS.md

@@ -76,6 +76,10 @@ This document was last updated at commit v4.3-197-g9085ed631.
    old behavior, use `awful.rules.rules = {}; awful.rules.rules = my_new_rules`.
  * `client:relative_move()` now default `nil` values to zero. The previous
    behavior made no sense.
+ * The tasklist and taglist widgets are no longer directly an instance of
+   it's main layout. Use the `base_layout` property to access the layout.
+   This allows to replace the layout at runtime. The previous behavior
+   was undocumented.
 
 <a name="v43"></a>
 # Awesome window manager framework version 4.3 changes

docs/common/client_theme.ldoc

@@ -344,6 +344,21 @@
  * @see request::border
  */
 
+/**
+ * The client border width for the fullscreen clients.
+ *
+ * This is the fallback if the more stateful version, like
+ * `beautiful.border_width_fullscreen_urgent` isn't set.
+ *
+ * @beautiful beautiful.border_width_fullscreen
+ * @param integer
+ * @see request::border
+ * @see beautiful.border_width_fullscreen_active
+ * @see beautiful.border_width_fullscreen_normal
+ * @see beautiful.border_width_fullscreen_urgent
+ * @see beautiful.border_width_fullscreen_new
+ */
+
 /**
  * The client opacity for the normal clients.
  *
@@ -391,7 +406,6 @@
  *
  * @beautiful beautiful.opacity_floating_normal
  * @param[opt=1] number
- * @see request::border
  */
 
 /**
@@ -424,6 +438,21 @@
  * @see request::border
  */
 
+/**
+ * The client opacity for the floating clients.
+ *
+ * A number between 0 and 1. This is the fallback if the more stateful
+ * variables, like `beautiful.opacity_floating_new` are not set.
+ *
+ * @beautiful beautiful.opacity_floating
+ * @param[opt=1] number
+ * @see request::border
+ * @see beautiful.opacity_floating_normal
+ * @see beautiful.opacity_floating_active
+ * @see beautiful.opacity_floating_urgent
+ * @see beautiful.opacity_floating_new
+ */
+
 /**
  * The client opacity for the normal maximized clients.
  *
@@ -431,7 +460,6 @@
  *
  * @beautiful beautiful.opacity_maximized_normal
  * @param[opt=1] number
- * @see request::border
  */
 
 /**
@@ -463,6 +491,22 @@
  * @param[opt=1] number
  * @see request::border
  */
+
+/**
+ * The client opacity for the maximized clients.
+ *
+ * A number between 0 and 1. This is the fallback if a more stateful
+ * variable, like `beautiful.opacity_maximized_urgent`, isn't set.
+ *
+ * @beautiful beautiful.opacity_maximized
+ * @param[opt=1] number
+ * @see request::border
+ * @see beautiful.opacity_maximized_normal
+ * @see beautiful.opacity_maximized_active
+ * @see beautiful.opacity_maximized_urgent
+ * @see beautiful.opacity_maximized_new
+ */
+
 /**
  * The client opacity for the normal fullscreen clients.
  *
@@ -470,7 +514,6 @@
  *
  * @beautiful beautiful.opacity_fullscreen_normal
  * @param[opt=1] number
- * @see request::border
  */
 
 /**
@@ -503,4 +546,21 @@
  * @see request::border
  */
 
+/**
+ * The client opacity for the fullscreen clients.
+ *
+ * A number between 0 and 1. This is the fallback if the variables
+ * for more stateful versions, like `beautiful.opacity_fullscreen_urgent`,
+ * are not set.
+ *
+ * @beautiful beautiful.opacity_fullscreen
+ * @param[opt=1] number
+ * @see request::border
+ * @see beautiful.opacity_fullscreen_new
+ * @see beautiful.opacity_fullscreen_urgent
+ * @see beautiful.opacity_fullscreen_active
+ * @see beautiful.opacity_fullscreen_normal
+ */
+
+
 /*

docs/common/cobject.ldoc

@@ -1,9 +1,11 @@
 */
 
 /** Disconnect from a signal.
+ *
  * @tparam string name The name of the signal.
  * @tparam function func The callback that should be disconnected.
  * @staticfct disconnect_signal
+ * @noreturn
  */
 
 /** Emit a signal.
@@ -13,12 +15,14 @@
  *   function receives the object as first argument and then any extra
  *   arguments that are given to emit_signal().
  * @staticfct emit_signal
+ * @noreturn
  */
 
 /** Connect to a signal.
  * @tparam string name The name of the signal.
  * @tparam function func The callback to call when the signal is emitted.
  * @staticfct connect_signal
+ * @noreturn
  */
 
 /*

docs/common/fixed.ldoc

@@ -68,6 +68,7 @@
 
 --- Reset the layout. This removes all widgets from the layout.
 -- @method reset
+-- @noreturn
 -- @emits widget::reset
 -- @emitstparam widget::reset widget self The layout.
 -- @interface layout

docs/common/notification_rules_index.ldoc

@@ -37,6 +37,7 @@
 --   <tr><td><a href='../core_components/notification.html#auto_reset_timeout'>auto\_reset\_timeout</a></td><td>If the timeout needs to be reset when a property changes</td></tr>
 --   <tr><td><a href='../core_components/notification.html#ignore_suspend'>ignore\_suspend</a></td><td></td></tr>
 --   <tr><td><a href='../core_components/notification.html#clients'>clients</a></td><td>A list of clients associated with this notification</td></tr>
+--   <tr><td><a href='../core_components/notification.html#max_width'>max\_width</a></td><td>The maximum popup width</td></tr>
 --   <tr><td><a href='../core_components/notification.html#app_name'>app\_name</a></td><td>The application name specified by the notification</td></tr>
 --   <tr><td><a href='../core_components/notification.html#widget_template'>widget\_template</a></td><td>The widget template used to represent the notification</td></tr>
 -- </table>

docs/common/object.ldoc

@@ -3,6 +3,8 @@
 -- @tparam string name The name of the signal.
 -- @tparam function func The callback that should be disconnected.
 -- @method disconnect_signal
+-- @treturn boolean `true` when the function was disconnected or `false` if it
+--  wasn't found.
 -- @baseclass gears.object
 
 --- Emit a signal.
@@ -12,12 +14,14 @@
 --   function receives the object as first argument and then any extra
 --   arguments that are given to emit_signal().
 -- @method emit_signal
+-- @noreturn
 -- @baseclass gears.object
 
 --- Connect to a signal.
 -- @tparam string name The name of the signal.
 -- @tparam function func The callback to call when the signal is emitted.
 -- @method connect_signal
+-- @noreturn
 -- @baseclass gears.object
 
 --- Connect to a signal weakly.
@@ -31,4 +35,5 @@
 -- @tparam string name The name of the signal.
 -- @tparam function func The callback to call when the signal is emitted.
 -- @method weak_connect_signal
+-- @noreturn
 -- @baseclass gears.object

docs/common/signals.ldoc

@@ -10,7 +10,8 @@
 --
 -- @tparam string name The name of the signal
 -- @tparam function func The function to attach
--- @function naughty.connect_signal
+-- @noreturn
+-- @staticfct naughty.connect_signal
 -- @usage naughty.connect_signal("added", function(notif)
 --    -- do something
 -- end)
@@ -18,10 +19,11 @@
 --- Emit a module signal.
 -- @tparam string name The signal name.
 -- @param ... The signal callback arguments
--- @function naughty.emit_signal
+-- @noreturn
+-- @staticfct naughty.emit_signal
 
 --- Disconnect a signal from a source.
 -- @tparam string name The name of the signal
 -- @tparam function func The attached function
--- @function naughty.disconnect_signal
+-- @staticfct naughty.disconnect_signal
 -- @treturn boolean If the disconnection was successful

docs/common/wibox.ldoc

@@ -2,7 +2,9 @@
 --
 -- @baseclass wibox
 -- @property border_width
--- @param integer
+-- @tparam[opt=0] integer border_width
+-- @propertyunit pixel
+-- @negativeallowed false
 -- @propemits false false
 
 --- Border color.
@@ -25,21 +27,22 @@
 --
 -- @baseclass wibox
 -- @property border_color
--- @param string
+-- @tparam[opt=beautiful.fg_normal] string border_color
 -- @propemits false false
 
 --- On top of other windows.
 --
 -- @baseclass wibox
 -- @property ontop
--- @param boolean
+-- @tparam[opt=false] boolean ontop
 -- @propemits false false
 
 --- The mouse cursor.
 --
 -- @baseclass wibox
 -- @property cursor
--- @param string
+-- @tparam[opt=nil] string|nil cursor
+-- @propertytype nil Do not change the mouse cursor.
 -- @see mouse
 -- @propemits false false
 
@@ -47,21 +50,23 @@
 --
 -- @baseclass wibox
 -- @property visible
--- @param boolean
+-- @tparam[opt=false] boolean visible
 -- @propemits false false
 
 --- The opacity of the wibox, between 0 and 1.
 --
 -- @baseclass wibox
 -- @property opacity
--- @tparam number opacity (between 0 and 1)
+-- @tparam[opt=true] number opacity
+-- @rangestart 0.0
+-- @rangestop 1.0
 -- @propemits false false
 
 --- The window type (desktop, normal, dock, ...).
 --
 -- @baseclass wibox
 -- @property type
--- @param string
+-- @tparam[opt=""] string type
 -- @see client.type
 -- @propemits false false
 
@@ -69,38 +74,49 @@
 --
 -- @baseclass wibox
 -- @property x
--- @param integer
+-- @tparam[opt=0] integer x
+-- @propertyunit pixel
+-- @negativeallowed true
 -- @propemits false false
 
 --- The y coordinates.
 --
 -- @baseclass wibox
 -- @property y
--- @param integer
+-- @tparam[opt=0] integer y
+-- @propertyunit pixel
+-- @negativeallowed true
 -- @propemits false false
 
 --- The width of the wibox.
 --
 -- @baseclass wibox
 -- @property width
--- @param width
+-- @tparam[opt=1] integer width
+-- @propertyunit pixel
+-- @rangestart 1
+-- @negativeallowed false
 -- @propemits false false
 
 --- The height of the wibox.
 --
 -- @baseclass wibox
 -- @property height
--- @param height
+-- @tparam[opt=1] integer height
+-- @propertyunit pixel
+-- @rangestart 1
+-- @negativeallowed false
 -- @propemits false false
 
 --- The wibox screen.
 --
 -- @baseclass wibox
 -- @property screen
--- @param screen
+-- @tparam screen screen
+-- @propertydefault The screen which contains `0x0`.
 -- @propemits true false
 
----  The wibox's `drawable`.
+--  The wibox's `drawable`.
 --
 -- @baseclass wibox
 -- @property drawable
@@ -110,14 +126,15 @@
 --- The widget that the `wibox` displays.
 -- @baseclass wibox
 -- @property widget
--- @param widget
+-- @tparam[opt=nil] widget|nil widget
 -- @propemits true false
 
 --- The X window id.
 --
 -- @baseclass wibox
 -- @property window
--- @param string
+-- @tparam string window
+-- @propertydefault Autogenerated.
 -- @see client.window
 -- @propemits false false
 
@@ -129,7 +146,8 @@
 --
 -- @baseclass wibox
 -- @property shape_bounding
--- @param surface._native
+-- @tparam surface._native shape_bounding
+-- @propertydefault Fill all pixels.
 -- @propemits false false
 -- @see shape
 
@@ -140,7 +158,8 @@
 --
 -- @baseclass wibox
 -- @property shape_clip
--- @param surface._native
+-- @tparam surface._native shape_clip
+-- @propertydefault Fill all pixels.
 -- @propemits false false
 -- @see shape
 
@@ -152,7 +171,8 @@
 --
 -- @baseclass wibox
 -- @property shape_input
--- @param surface._native
+-- @tparam surface._native shape_input
+-- @propertydefault Fill all pixels.
 -- @propemits false false
 -- @see input_passthrough
 
@@ -160,7 +180,7 @@
 --
 -- @baseclass wibox
 -- @property shape
--- @tparam gears.shape shape
+-- @tparam[opt=gears.shape.rectangle] shape shape
 -- @propemits true false
 -- @see gears.shape
 
@@ -174,7 +194,7 @@
 --
 -- @baseclass wibox
 -- @property input_passthrough
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean input_passthrough
 -- @see shape_input
 -- @propemits true false
 
@@ -182,15 +202,17 @@
 --
 -- @baseclass wibox
 -- @property buttons
--- @param buttons_table A table of buttons objects, or nothing.
+-- @tparam[opt={}] table buttons A table of buttons objects, or nothing.
+-- @tablerowtype A list of `awful.button`s.
 -- @propemits false false
 
 --- Get or set wibox geometry. That's the same as accessing or setting the x,
 -- y, width or height properties of a wibox.
 --
 -- @baseclass wibox
--- @param A table with coordinates to modify.
--- @return A table with wibox coordinates and geometry.
+-- @tparam[opt=nil] table|nil geo A table with coordinates to modify. If
+--  nothing is specified, it only returns the current geometry.
+-- @treturn table A table with wibox coordinates and geometry.
 -- @method geometry
 -- @emits property::geometry When the geometry change.
 -- @emitstparam property::geometry table geo The geometry table.
@@ -205,36 +227,18 @@
 -- the side of the screen).
 --
 -- @baseclass wibox
--- @param strut A table with new strut, or nothing
 -- @return The wibox strut in a table.
 -- @method struts
+-- @tparam table struts A table with new strut, or nothing.
 -- @see client.struts
 -- @emits property::struts
 
---- The default background color.
---
--- The background color can be transparent. If there is a
--- compositing manager such as compton, then it will be
--- real transparency and may include blur (provided by the
--- compositor). When there is no compositor, it will take
--- a picture of the wallpaper and blend it.
---
--- @baseclass wibox
--- @beautiful beautiful.bg_normal
--- @param color
--- @see bg
-
---- The default foreground (text) color.
--- @baseclass wibox
--- @beautiful beautiful.fg_normal
--- @param color
--- @see fg
-
 --- Set a declarative widget hierarchy description.
 -- See [The declarative layout system](../documentation/03-declarative-layout.md.html)
 -- @param args An array containing the widgets disposition
 -- @baseclass wibox
 -- @method setup
+-- @noreturn
 
 --- The background of the wibox.
 --
@@ -246,8 +250,8 @@
 --
 -- @baseclass wibox
 -- @property bg
--- @tparam c The background to use. This must either be a cairo pattern object,
---   nil or a string that gears.color() understands.
+-- @tparam[opt=beautiful.bg_normal] color bg The background to use. This
+--  must either be a cairo pattern object, nil or a string that gears.color() understands.
 -- @see gears.color
 -- @propemits true false
 -- @usebeautiful beautiful.bg_normal The default (fallback) bg color.
@@ -257,18 +261,17 @@
 -- If `image` is a function, it will be called with `(context, cr, width, height)`
 -- as arguments. Any other arguments passed to this method will be appended.
 --
--- @tparam gears.suface|string|function image A background image or a function.
 -- @baseclass wibox
 -- @property bgimage
+-- @tparam[opt=nil] image|nil bgimage
 -- @see gears.surface
 -- @propemits true false
 
 --- The foreground (text) of the wibox.
--- @tparam color c The foreground to use. This must either be a cairo pattern object,
---   nil or a string that gears.color() understands.
+--
 -- @baseclass wibox
 -- @property fg
--- @param color
+-- @tparam[opt=beautiful.fg_normal] color fg
 -- @see gears.color
 -- @propemits true false
 -- @usebeautiful beautiful.fg_normal The default (fallback) fg color.

docs/common/widget.ldoc

@@ -11,41 +11,58 @@
 
 --- Get or set the children elements.
 -- @property children
--- @tparam table children The children.
+-- @tparam table children
+-- @tablerowtype A list of `widget`s.
 -- @baseclass wibox.widget
+-- @see all_children
 
 --- Get all direct and indirect children widgets.
 -- This will scan all containers recursively to find widgets
 -- Warning: This method it prone to stack overflow id the widget, or any of its
 -- children, contain (directly or indirectly) itself.
 -- @property all_children
--- @tparam table children The children.
+-- @tparam table all_children
+-- @tablerowtype A list of `widget`s.
 -- @baseclass wibox.widget
+-- @see children
 
 --- Set a declarative widget hierarchy description.
 -- See [The declarative layout system](../documentation/03-declarative-layout.md.html)
--- @param args An array containing the widgets disposition
+-- @tparam table args An array containing the widgets disposition
 -- @method setup
+-- @noreturn
 -- @baseclass wibox.widget
 
 --- Force a widget height.
 -- @property forced_height
--- @tparam number|nil height The height (`nil` for automatic)
+-- @tparam number|nil forced_height
+-- @propertytype nil Let the layout decide the height. Usually using the widget
+--  native height.
+-- @propertytype number Enforce a number of pixels.
+-- @negativeallowed false
 -- @baseclass wibox.widget
+-- @see forced_width
 
 --- Force a widget width.
 -- @property forced_width
--- @tparam number|nil width The width (`nil` for automatic)
+-- @tparam number|nil forced_width
+-- @propertytype nil Let the layout decide the width. Usually using the widget
+--  native width.
+-- @propertytype number Enforce a number of pixels.
+-- @negativeallowed false
 -- @baseclass wibox.widget
+-- @see forced_height
 
 --- The widget opacity (transparency).
 -- @property opacity
--- @tparam[opt=1] number opacity The opacity (between 0 and 1)
+-- @tparam[opt=1] number opacity.
+-- @rangestart 0.0
+-- @rangestop 1.0
 -- @baseclass wibox.widget
 
 --- The widget visibility.
 -- @property visible
--- @param boolean
+-- @tparam[opt=true] boolean visible
 -- @baseclass wibox.widget
 
 --- The widget buttons.
@@ -53,13 +70,15 @@
 -- The table contains a list of `awful.button` objects.
 --
 -- @property buttons
--- @param table
+-- @tparam[opt={}] table buttons
 -- @see awful.button
+-- @tablerowtype A list of `awful.button`.
 -- @baseclass wibox.widget
 
 --- Add a new `awful.button` to this widget.
 -- @tparam awful.button button The button to add.
 -- @method add_button
+-- @noreturn
 -- @baseclass wibox.widget
 
 --- Emit a signal and ensure all parent widgets in the hierarchies also
@@ -69,6 +88,7 @@
 -- @param ... Other arguments
 -- @baseclass wibox.widget
 -- @method emit_signal_recursive
+-- @noreturn
 
 --- When the layout (size) change.
 -- This signal is emitted when the previous results of `:layout()` and `:fit()`
@@ -96,7 +116,7 @@
 -- @tparam number button The button number.
 -- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift)
 -- @tparam table find_widgets_result The entry from the result of
--- @{wibox.drawable:find_widgets} for the position that the mouse hit.
+-- @{wibox:find_widgets} for the position that the mouse hit.
 -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
 -- the widget.
 -- @tparam widget find_widgets_result.widget The widget being displayed.
@@ -127,7 +147,7 @@
 -- @tparam number button The button number.
 -- @tparam table mods The modifiers (mod4, mod1 (alt), Control, Shift)
 -- @tparam table find_widgets_result The entry from the result of
--- @{wibox.drawable:find_widgets} for the position that the mouse hit.
+-- @{wibox:find_widgets} for the position that the mouse hit.
 -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
 -- the widget.
 -- @tparam widget find_widgets_result.widget The widget being displayed.
@@ -152,7 +172,7 @@
 -- @signal mouse::enter
 -- @tparam table self The current object instance itself.
 -- @tparam table find_widgets_result The entry from the result of
--- @{wibox.drawable:find_widgets} for the position that the mouse hit.
+-- @{wibox:find_widgets} for the position that the mouse hit.
 -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
 -- the widget.
 -- @tparam widget find_widgets_result.widget The widget being displayed.
@@ -177,7 +197,7 @@
 -- @signal mouse::leave
 -- @tparam table self The current object instance itself.
 -- @tparam table find_widgets_result The entry from the result of
--- @{wibox.drawable:find_widgets} for the position that the mouse hit.
+-- @{wibox:find_widgets} for the position that the mouse hit.
 -- @tparam wibox.drawable find_widgets_result.drawable The drawable containing
 -- the widget.
 -- @tparam widget find_widgets_result.widget The widget being displayed.

docs/images/client_geo.svg

@@ -67,11 +67,11 @@
      inkscape:connector-curvature="0"
      id="path6072"
      d="m 58.889889,0.75 402.388891,0 0,238.5 -402.388891,0 z"
-     style="fill:none;stroke:#000000;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:10, 4;stroke-dashoffset:1;stroke-opacity:0.26666703"
+     class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:10, 4;stroke-dashoffset:1;stroke-opacity:0.26666703"
      sodipodi:nodetypes="ccccc" />
   <text
      xml:space="preserve"
-     style="font-style:normal;font-weight:normal;font-size:13.13514996px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:0.2;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+     class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:13.13514996px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:0.2;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
      x="63.513626"
      y="13.124383"
      id="text6180"
@@ -99,7 +99,7 @@
          inkscape:connector-curvature="0" />
       <text
          xml:space="preserve"
-         style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
          x="131.39223"
          y="30.661503"
          id="text6192"
@@ -122,7 +122,7 @@
          id="text6196"
          y="217.16113"
          x="122.56128"
-         style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
          xml:space="preserve"><tspan
            y="217.16113"
            x="122.56128"
@@ -139,7 +139,7 @@
          sodipodi:nodetypes="sssssssss" />
       <text
          xml:space="preserve"
-         style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:108.00000429%;font-family:sans-serif;letter-spacing:-0.024px;word-spacing:0px;writing-mode:tb-rl;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:108.00000429%;font-family:sans-serif;letter-spacing:-0.024px;word-spacing:0px;writing-mode:tb-rl;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
          x="37.922375"
          y="38.963093"
          id="text6200"
@@ -163,7 +163,7 @@
          id="text6204"
          y="32.857822"
          x="278.37604"
-         style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;writing-mode:tb-rl;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;writing-mode:tb-rl;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
          xml:space="preserve"><tspan
            y="278.37604"
            x="32.857822"
@@ -172,7 +172,7 @@
     </g>
     <text
        xml:space="preserve"
-       style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        x="124.76434"
        y="124.29873"
        id="text6208"
@@ -224,7 +224,7 @@
          id="text6241"
          y="30.661503"
          x="131.39223"
-         style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
          xml:space="preserve"><tspan
            y="30.661503"
            x="131.39223"
@@ -232,7 +232,7 @@
            sodipodi:role="line">Top titlebar</tspan></text>
       <text
          xml:space="preserve"
-         style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
          x="122.56128"
          y="217.16113"
          id="text6245"
@@ -246,7 +246,7 @@
          id="text6249"
          y="38.963093"
          x="37.922375"
-         style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:108.00000429%;font-family:sans-serif;letter-spacing:-0.024px;word-spacing:0px;writing-mode:tb-rl;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:108.00000429%;font-family:sans-serif;letter-spacing:-0.024px;word-spacing:0px;writing-mode:tb-rl;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
          xml:space="preserve"><tspan
            style="line-height:100%;letter-spacing:-0.024px"
            y="37.922375"
@@ -255,7 +255,7 @@
            sodipodi:role="line">Left titlebar</tspan></text>
       <text
          xml:space="preserve"
-         style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;writing-mode:tb-rl;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;writing-mode:tb-rl;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
          x="278.37604"
          y="32.857822"
          id="text6253"
@@ -266,7 +266,7 @@
            y="278.37604">Right titlebar</tspan></text>
       <text
          xml:space="preserve"
-         style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
          x="124.76434"
          y="124.29873"
          id="text6257"
@@ -290,12 +290,12 @@
      id="circle6292"
      style="opacity:1;fill:none;fill-opacity:1;stroke:#617fff;stroke-width:1.39999998;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
   <path
-     style="fill:#000000;fill-opacity:0;fill-rule:evenodd;stroke:#617fff;stroke-width:1.60000002;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+     class=".svg_fill" style="fill:currentcolor;;fill-opacity:0;fill-rule:evenodd;stroke:#617fff;stroke-width:1.60000002;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
      d="M 327.02878,21.111111 419.251,82.222224"
      id="path6313"
      inkscape:connector-curvature="0" />
   <path
-     style="fill:#000000;fill-opacity:0;fill-rule:evenodd;stroke:#617fff;stroke-width:1.60000002;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+     class=".svg_fill" style="fill:currentcolor;;fill-opacity:0;fill-rule:evenodd;stroke:#617fff;stroke-width:1.60000002;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
      d="M 295.08433,62.638889 339.251,162.77778"
      id="path6315"
      inkscape:connector-curvature="0"
@@ -317,7 +317,7 @@
      id="text6192-0"
      y="221.88589"
      x="327.72714"
-     style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+     class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
      xml:space="preserve"><tspan
        y="221.88589"
        x="327.72714"
@@ -328,24 +328,24 @@
      id="text6192-5"
      y="208.45212"
      x="328.16382"
-     style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+     class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
      xml:space="preserve"><tspan
        y="208.45212"
        x="328.16382"
        id="tspan6194-4"
        sodipodi:role="line">Shape clip outline</tspan></text>
   <path
-     style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+     class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
      d="m 415.22882,118.2205 40.06938,0 0,99.78062 -6.2854,0"
      id="path6349"
      inkscape:connector-curvature="0" />
   <path
-     style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+     class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
      d="m 410.63989,133.61111 18.88889,0 0,71.11111 -6.94444,0"
      id="path6351"
      inkscape:connector-curvature="0" />
   <path
-     style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+     class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
      d="m 418.93898,200.35818 3.33912,0 0,8.64241 -3.33912,0"
      id="path6353"
      inkscape:connector-curvature="0" />
@@ -353,27 +353,27 @@
      inkscape:connector-curvature="0"
      id="path6355"
      d="m 445.91815,214.03874 3.33912,0 0,8.64241 -3.33912,0"
-     style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
+     class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
   <path
      inkscape:connector-curvature="0"
      id="path6357"
      d="m 371.60211,105.68444 3.33912,0 0,5.30329 -3.33912,0"
-     style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+     class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
      sodipodi:nodetypes="cccc" />
   <path
      inkscape:connector-curvature="0"
      id="path6359"
      d="m 385.31699,32.441513 -3.33912,0 0,8.64241 3.33912,0"
-     style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
+     class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
   <path
-     style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+     class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:0.80000001px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
      d="m 375.36211,108.26388 2.77778,0 0,-71.319435 3.61111,0"
      id="path6361"
      inkscape:connector-curvature="0"
      sodipodi:nodetypes="cccc" />
   <text
      xml:space="preserve"
-     style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+     class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
      x="386.21936"
      y="40.118782"
      id="text6363"

docs/images/mouse.svg

@@ -67,13 +67,13 @@
          inkscape:connector-curvature="0"
          id="path4136"
          d="m -728.15879,608.42602 178.5142,0 c 9.38939,0.26627 10.95278,7.73823 10.83892,14.69669 l 0,230.46648 c 0.30959,23.52499 -24.37716,50.18749 -47.93254,50.01303 l -104.98806,0.29423 c -20.09841,0.0248 -45.84989,-25.43284 -46.17689,-51.01859 l 0.0204,-227.59279 c 0.18644,-8.43842 1.99483,-16.50279 9.72396,-16.85905 z"
-         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.50971645;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+         class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:0.50971645;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
       <path
          sodipodi:nodetypes="cc"
          inkscape:connector-curvature="0"
          id="path4138"
          d="m -733.20425,673.55031 189.76854,0"
-         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.87379962;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+         class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:0.87379962;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
       <path
          sodipodi:nodetypes="cccccccccccc"
          inkscape:connector-curvature="0"
@@ -96,14 +96,14 @@
          id="rect4768"
          style="opacity:1;fill:#617fff;fill-opacity:0.49019608;stroke:#617fff;stroke-width:1.63500068;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
       <path
-         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+         class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
          d="m -644.91259,651.46192 -6.56599,0.12226 0,106.78495 6.87951,-0.023"
          id="path8458"
          inkscape:connector-curvature="0"
          sodipodi:nodetypes="cccc" />
       <text
          xml:space="preserve"
-         style="font-style:normal;font-weight:normal;font-size:14.765769px;line-height:125%;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:14.765769px;line-height:125%;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
          x="-703.82648"
          y="718.50195"
          id="text8466"><tspan
@@ -119,7 +119,7 @@
          id="text5405"
          y="717.49182"
          x="-582.11389"
-         style="font-style:normal;font-weight:normal;font-size:14.765769px;line-height:125%;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:14.765769px;line-height:125%;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
          xml:space="preserve"><tspan
            y="717.49182"
            x="-582.11389"
@@ -134,16 +134,16 @@
          inkscape:connector-curvature="0"
          id="path5413"
          d="m -644.66005,640.0977 -12.12183,0.12226 0,139.86744 12.81415,-0.023"
-         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+         class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
       <path
-         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+         class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
          d="m -644.91259,627.47079 -17.42513,0.12226 0,171.18217 18.36999,0.0243"
          id="path5415"
          inkscape:connector-curvature="0"
          sodipodi:nodetypes="cccc" />
       <text
          xml:space="preserve"
-         style="font-style:normal;font-weight:normal;font-size:14.765769px;line-height:125%;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:14.765769px;line-height:125%;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
          x="-588.33746"
          y="785.02411"
          id="text5417"><tspan
@@ -155,7 +155,7 @@
          id="text5425"
          y="803.3548"
          x="-584.96796"
-         style="font-style:normal;font-weight:normal;font-size:14.765769px;line-height:125%;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:14.765769px;line-height:125%;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
          xml:space="preserve"><tspan
            id="tspan5427"
            y="803.3548"
@@ -165,7 +165,7 @@
          id="text5429"
          y="763.70624"
          x="-596.21576"
-         style="font-style:normal;font-weight:normal;font-size:14.765769px;line-height:125%;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+         class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:14.765769px;line-height:125%;font-family:sans-serif;text-align:center;letter-spacing:0px;word-spacing:0px;text-anchor:middle;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
          xml:space="preserve"><tspan
            id="tspan5431"
            y="763.70624"
@@ -176,9 +176,9 @@
          inkscape:connector-curvature="0"
          id="path5433"
          d="m -705.40715,646.22703 0,58.57067"
-         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+         class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
       <path
-         style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+         class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
          d="m -582.19286,646.22703 0,58.57067"
          id="path5435"
          inkscape:connector-curvature="0"
@@ -188,9 +188,9 @@
          cy="703.61224"
          cx="-705.53571"
          id="path5437"
-         style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+         class=".svg_fill" style="opacity:1;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
       <circle
-         style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         class=".svg_fill" style="opacity:1;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
          id="circle5439"
          cx="-705.44647"
          cy="646.91583"
@@ -200,15 +200,15 @@
          cy="646.02295"
          cx="-582.23218"
          id="circle5441"
-         style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+         class=".svg_fill" style="opacity:1;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
       <circle
-         style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         class=".svg_fill" style="opacity:1;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
          id="circle5443"
          cx="-582.05359"
          cy="704.41583"
          r="2.3214285" />
       <circle
-         style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         class=".svg_fill" style="opacity:1;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
          id="circle5445"
          cx="-643.66077"
          cy="627.63007"
@@ -218,9 +218,9 @@
          cy="639.95148"
          cx="-643.66077"
          id="circle5447"
-         style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+         class=".svg_fill" style="opacity:1;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
       <circle
-         style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         class=".svg_fill" style="opacity:1;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
          id="circle5449"
          cx="-643.66077"
          cy="651.55859"
@@ -230,9 +230,9 @@
          cy="758.34442"
          cx="-645.08929"
          id="circle5451"
-         style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+         class=".svg_fill" style="opacity:1;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
       <circle
-         style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         class=".svg_fill" style="opacity:1;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
          id="circle5453"
          cx="-645.08929"
          cy="779.77301"
@@ -242,7 +242,7 @@
          cy="798.88013"
          cx="-645.08929"
          id="circle5455"
-         style="opacity:1;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
+         class=".svg_fill" style="opacity:1;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.75;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1" />
     </g>
   </g>
 </svg>

docs/images/progressbar.svg

@@ -76,115 +76,115 @@
          style="fill:#a800ff;fill-opacity:0.49019602;fill-rule:nonzero;stroke:#ffff00;stroke-width:2;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-opacity:1" />
     </g>
     <rect
-       style="fill:none;stroke:#000000;stroke-width:5.72931957;stroke-miterlimit:4;stroke-dasharray:17.18795897, 5.72931965;stroke-dashoffset:0;stroke-opacity:0.19282514"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:5.72931957;stroke-miterlimit:4;stroke-dasharray:17.18795897, 5.72931965;stroke-dashoffset:0;stroke-opacity:0.19282514"
        id="rect6202"
        width="223.72885"
        height="103.9784"
        x="-65.681862"
        y="-44.285286" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="m -65.681858,-44.285287 v -9.346375 h 33.880606 v 7.593928"
        id="path6204"
        inkscape:connector-curvature="0" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="m -68.602599,-44.285289 h -8.908263 v 22.781787 h 8.762225"
        id="path6206"
        inkscape:connector-curvature="0" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="m -68.456562,36.181149 h -8.178079 v 20.883305 h 8.032042"
        id="path6208"
        inkscape:connector-curvature="0" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="m 129.4237,62.613864 v 7.593929 h 27.16289 v -7.886004"
        id="path6210"
        inkscape:connector-curvature="0" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="m -23.039026,31.946074 v 7.009781 h -7.886004 v -7.009781"
        id="path6212"
        inkscape:connector-curvature="0" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="m 106.64191,32.530222 v 6.717706 h 16.9403 v -7.593927"
        id="path6214"
        inkscape:connector-curvature="0" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="m 124.45843,-16.830315 h 7.0098 v 6.425632 h -7.30186 v 0"
        id="path6216"
        inkscape:connector-curvature="0" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="m 99.632131,-12.157128 v -3.796965 h 6.717709 v 4.381114"
        id="path6218"
        inkscape:connector-curvature="0" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="m -34.721994,-21.211428 h -4.089039 v 3.50489 h 4.381113"
        id="path6220"
        inkscape:connector-curvature="0" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="m 132.05237,-13.325425 h 34.17266"
        id="path6222"
        inkscape:connector-curvature="0" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="M 102.58345,-16.2321 V -52.580964"
        id="path6224"
        inkscape:connector-curvature="0" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="m 115.18163,39.530362 v 40.06636"
        id="path6226"
        inkscape:connector-curvature="0" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="M 144.0955,70.509507 V 86.825191"
        id="path6228"
        inkscape:connector-curvature="0" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="m -26.702851,38.91078 v 27.261648 0"
        id="path6232"
        inkscape:connector-curvature="0" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="m -76.062956,45.313136 h -8.261102"
        id="path6234"
        inkscape:connector-curvature="0" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="m -78.541288,-33.580422 h -7.641524"
        id="path6236"
        inkscape:connector-curvature="0" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="m -47.975197,-54.646241 v -6.815411"
        id="path6238"
        inkscape:connector-curvature="0" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="M -39.404301,-19.226751 H -86.905655"
        id="path6240"
        inkscape:connector-curvature="0" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="M 40.212104,-63.526928 V 7.1055221"
        id="path6242"
        inkscape:connector-curvature="0" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="M 44.755712,28.584397 V 107.89101"
        id="path6244"
        inkscape:connector-curvature="0" />
     <text
        xml:space="preserve"
-       style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.43232989"
+       class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.43232989"
        x="-81.409393"
        y="-68.525108"
        id="text6248"><tspan
@@ -195,7 +195,7 @@
          style="stroke-width:1.43232989">margins.left</tspan></text>
     <text
        xml:space="preserve"
-       style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.43232989"
+       class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.43232989"
        x="53.016815"
        y="88.064354"
        id="text6252"><tspan
@@ -206,7 +206,7 @@
          style="stroke-width:1.43232989">paddings.right</tspan></text>
     <text
        xml:space="preserve"
-       style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.43232989"
+       class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.43232989"
        x="-173.14709"
        y="47.484715"
        id="text6256"><tspan
@@ -217,7 +217,7 @@
          style="stroke-width:1.43232989">margins.bottom</tspan></text>
     <text
        xml:space="preserve"
-       style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.43232989"
+       class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.43232989"
        x="-68.008377"
        y="80.629356"
        id="text6260"><tspan
@@ -228,7 +228,7 @@
          id="tspan6262">paddings.left</tspan></text>
     <text
        xml:space="preserve"
-       style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.43232989"
+       class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.43232989"
        x="25.046478"
        y="-68.112053"
        id="text6268"><tspan
@@ -239,7 +239,7 @@
          style="stroke-width:1.43232989">color</tspan></text>
     <text
        xml:space="preserve"
-       style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.43232989"
+       class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.43232989"
        x="0.55879593"
        y="121.52184"
        id="text6272"><tspan
@@ -249,13 +249,13 @@
          y="121.52184"
          style="stroke-width:1.43232989">background_color</tspan></text>
     <path
-       style="fill:none;stroke:#000000;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.43232989px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="M -33.72479,8.7577433 H -101.0528"
        id="path6274"
        inkscape:connector-curvature="0" />
     <text
        xml:space="preserve"
-       style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.43232989"
+       class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.43232989"
        x="-171.67308"
        y="10.752149"
        id="text6278"><tspan
@@ -266,7 +266,7 @@
          style="stroke-width:1.43232989">border_color</tspan></text>
     <text
        xml:space="preserve"
-       style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.43232989"
+       class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.43232989"
        x="59.921341"
        y="-56.416924"
        id="text6282"><tspan
@@ -277,7 +277,7 @@
          style="stroke-width:1.43232989">bar_border_width</tspan></text>
     <text
        xml:space="preserve"
-       style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.43232989"
+       class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.43232989"
        x="176.52036"
        y="-13.960297"
        id="text6286"><tspan
@@ -288,7 +288,7 @@
          style="stroke-width:1.43232989">paddings.top</tspan></text>
     <text
        xml:space="preserve"
-       style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.43232989"
+       class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.43232989"
        x="114.56205"
        y="103.76046"
        id="text6290"><tspan
@@ -299,7 +299,7 @@
          style="stroke-width:1.43232989">margins.right</tspan></text>
     <text
        xml:space="preserve"
-       style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.43232989"
+       class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.43232989"
        x="-161.98454"
        y="-15.825125"
        id="text6294"><tspan
@@ -310,7 +310,7 @@
          style="stroke-width:1.43232989">border_width</tspan></text>
     <text
        xml:space="preserve"
-       style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1.43232989"
+       class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:11.45863914px;line-height:1.25;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1.43232989"
        x="-154.04338"
        y="-30.323574"
        id="text6298"><tspan

docs/images/tag_props.svg

@@ -52,12 +52,12 @@
      inkscape:connector-curvature="0"
      id="path5786"
      d="m 99.744949,82.18258 318.500001,0 0,238.5 -318.500001,0 z m 0,0"
-     style="fill:none;stroke:#000000;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:10, 4;stroke-dashoffset:1;stroke-opacity:0.26666703" />
+     class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:10, 4;stroke-dashoffset:1;stroke-opacity:0.26666703" />
   <path
      inkscape:connector-curvature="0"
      id="path5788"
      d="m 108.99495,91.43258 300,0 0,220 -300,0 z m 0,0"
-     style="fill:none;stroke:#000000;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:10, 4;stroke-dashoffset:1;stroke-opacity:0.2" />
+     class=".svg_stroke" style="fill:none;stroke:currentcolor;;stroke-width:1.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:10;stroke-dasharray:10, 4;stroke-dashoffset:1;stroke-opacity:0.2" />
   <path
      inkscape:connector-curvature="0"
      id="path5792"
@@ -77,12 +77,12 @@
      style="fill:#617fff;fill-opacity:0.49019602;fill-rule:nonzero;stroke:#617fff;stroke-width:1.55999994;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
      sodipodi:nodetypes="sssssssss" />
   <path
-     style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.20000005;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+     class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.20000005;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
      d="m 118.6368,77.0879 0,-10.21376 135.92164,0 0,11.39227"
      id="path7589"
      inkscape:connector-curvature="0" />
   <path
-     style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.36000001;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+     class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.36000001;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
      d="m 182.27641,66.4813 0,-10.99944"
      id="path7595"
      inkscape:connector-curvature="0" />
@@ -90,21 +90,21 @@
      inkscape:connector-curvature="0"
      id="path7597"
      d="m 427.60318,224.3777 10.21376,0 0,15.32064 -10.14227,0"
-     style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.20000005;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+     class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.20000005;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
      sodipodi:nodetypes="cccc" />
   <path
      inkscape:connector-curvature="0"
      id="path7599"
      d="m 438.44336,232.64825 10.99944,0"
-     style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.36000001;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+     class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.36000001;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
   <path
      sodipodi:nodetypes="cccc"
-     style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.20000005;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+     class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.20000005;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
      d="m 265.37038,328.5978 0,10.21376 -15.32064,0 0,-10.14227"
      id="path7601"
      inkscape:connector-curvature="0" />
   <path
-     style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.20000005;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+     class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.20000005;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
      d="m 258.99495,338.6548 0,9.44444 183.33334,0 0,-114.44443"
      id="path7603"
      inkscape:connector-curvature="0"
@@ -114,21 +114,21 @@
      id="text7607"
      y="235.37877"
      x="452.8934"
-     style="font-style:normal;font-weight:normal;font-size:11.81261539px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+     class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:11.81261539px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
      xml:space="preserve"><tspan
        y="235.37877"
        x="452.8934"
        id="tspan7609"
        sodipodi:role="line">Gaps</tspan></text>
   <path
-     style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.20000005;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+     class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.20000005;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
      d="m 399.82829,90.321468 0,-26.432579 -20.55556,0.04369"
      id="path7611"
      inkscape:connector-curvature="0"
      sodipodi:nodetypes="ccc" />
   <text
      xml:space="preserve"
-     style="font-style:normal;font-weight:normal;font-size:11.81261539px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+     class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:11.81261539px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
      x="320.79419"
      y="67.281029"
      id="text7613"
@@ -141,28 +141,28 @@
      inkscape:connector-curvature="0"
      id="path7617"
      d="m 123.14816,328.5978 0,10.21376 -15.32064,0 0,-10.14227"
-     style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.20000005;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+     class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.20000005;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
      sodipodi:nodetypes="cccc" />
   <path
      sodipodi:nodetypes="cccc"
-     style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.20000005;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+     class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.20000005;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
      d="m 96.150273,107.47611 -10.213761,0 0,-15.32064 10.142271,0"
      id="path7619"
      inkscape:connector-curvature="0" />
   <path
-     style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.20000005;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+     class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.20000005;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
      d="m 85.10606,100.32147 -8.333333,0 0,248.33333 38.333333,0"
      id="path7623"
      inkscape:connector-curvature="0" />
   <path
-     style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.20000005;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+     class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.20000005;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
      d="m 115.10606,339.21036 0,24.84505 4.91046,0.0712"
      id="path7625"
      inkscape:connector-curvature="0"
      sodipodi:nodetypes="ccc" />
   <text
      xml:space="preserve"
-     style="font-style:normal;font-weight:normal;font-size:11.81261539px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+     class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:11.81261539px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
      x="122.60548"
      y="366.58011"
      id="text7627"
@@ -178,7 +178,7 @@
      inkscape:connector-curvature="0" />
   <text
      xml:space="preserve"
-     style="font-style:normal;font-weight:normal;font-size:11.81261539px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+     class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:11.81261539px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
      x="130.15106"
      y="52.780128"
      id="text7591"
@@ -216,7 +216,7 @@
      id="text7651"
      y="382.34006"
      x="122.60548"
-     style="font-style:normal;font-weight:normal;font-size:11.81261539px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+     class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:11.81261539px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
      xml:space="preserve"><tspan
        y="382.34006"
        x="122.60548"
@@ -226,19 +226,19 @@
      inkscape:connector-curvature="0"
      id="path8456"
      d="m 118.6368,77.0879 0,-10.21376 135.92164,0 0,11.39227"
-     style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.20000005;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+     class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.20000005;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
   <path
      sodipodi:nodetypes="ccc"
      inkscape:connector-curvature="0"
      id="path8458"
      d="m 413.99495,82.265912 0,-40.877023 -33.88889,0.321471"
-     style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:1.20000005;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
+     class=".svg_stroke" style="fill:none;fill-rule:evenodd;stroke:currentcolor;;stroke-width:1.20000005;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1" />
   <text
      sodipodi:linespacing="125%"
      id="text8460"
      y="38.719765"
      x="285.3501"
-     style="font-style:normal;font-weight:normal;font-size:17.02204132px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+     class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:17.02204132px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
      xml:space="preserve"><tspan
        y="38.719765"
        x="285.3501"
@@ -253,7 +253,7 @@
      id="text8466"
      y="45.725838"
      x="310.60031"
-     style="font-style:normal;font-weight:normal;font-size:11.81261539px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+     class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:11.81261539px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
      xml:space="preserve"><tspan
        y="45.725838"
        x="310.60031"
@@ -261,7 +261,7 @@
        sodipodi:role="line">Screen area</tspan></text>
   <text
      xml:space="preserve"
-     style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+     class=".svg_fill" style="font-style:normal;font-weight:normal;font-size:10.9279623px;line-height:125%;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:currentcolor;;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
      x="237.01671"
      y="18.350338"
      id="text6363"

docs/images/warning_icon.svg

@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="32mm"
+   height="32mm"
+   viewBox="0 0 32 32"
+   version="1.1"
+   id="svg8"
+   inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)"
+   sodipodi:docname="warning_icon.svg">
+  <defs
+     id="defs2" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="1.979899"
+     inkscape:cx="74.464747"
+     inkscape:cy="-39.991417"
+     inkscape:document-units="mm"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     showguides="true"
+     inkscape:guide-bbox="true"
+     inkscape:window-width="1916"
+     inkscape:window-height="980"
+     inkscape:window-x="2"
+     inkscape:window-y="32"
+     inkscape:window-maximized="1"
+     fit-margin-top="0"
+     fit-margin-left="0"
+     fit-margin-right="0"
+     fit-margin-bottom="0">
+    <inkscape:grid
+       type="xygrid"
+       id="grid856"
+       originx="-0.056405092"
+       originy="-80.825357" />
+    <sodipodi:guide
+       position="40.835834,95.839799"
+       orientation="0,1"
+       id="guide858"
+       inkscape:locked="false" />
+    <sodipodi:guide
+       position="100.97147,-58.641987"
+       orientation="0,1"
+       id="guide860"
+       inkscape:locked="false" />
+  </sodipodi:namedview>
+  <metadata
+     id="metadata5">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-0.05640609,-184.17464)">
+    <path
+       style="opacity:1;fill:#cdcdcd;fill-opacity:0.94170403;stroke-width:0.04273237"
+       d="m 15.987264,186.03934 c -0.51293,0.002 -1.011107,0.29721 -1.303535,0.87343 L 7.4496946,199.4451 0.19454716,212.01408 c -0.41426919,0.8099 0.11377925,2.28705 1.44206664,2.28967 H 16.02657 30.8287 c 0.832347,0 1.63675,-1.03166 0.995843,-2.34869 l -7.2211,-12.50996 -7.223935,-12.5148 c -0.351606,-0.60004 -0.879318,-0.89253 -1.392244,-0.89096 z m 0.03104,4.53979 c 0.728062,0 1.279641,0.27585 1.654705,0.82752 0.386093,0.55168 0.579079,1.5502 0.579079,2.99559 0,0.50754 -0.02754,1.00954 -0.0827,1.50605 -0.05516,0.48549 -0.126892,1.02062 -0.215143,1.60539 l -1.158243,8.40755 h -1.605051 l -1.075539,-7.76208 c -0.09928,-0.78337 -0.193071,-1.45643 -0.28132,-2.01914 -0.08824,-0.57375 -0.132357,-1.16407 -0.132357,-1.77092 0,-1.31298 0.198563,-2.27287 0.595688,-2.87972 0.408155,-0.60685 0.981789,-0.91024 1.720883,-0.91024 z m 0.03305,16.9475 c 0.71703,0 1.323786,0.24829 1.820192,0.7448 0.496405,0.49651 0.744566,1.10332 0.744566,1.82049 0,0.72822 -0.248161,1.34608 -0.744566,1.85363 -0.496406,0.50754 -1.103162,0.76133 -1.820192,0.76133 -0.728061,0 -1.345802,-0.25379 -1.85324,-0.76133 -0.507436,-0.50755 -0.76109,-1.12541 -0.76109,-1.85363 0,-0.71717 0.253654,-1.32398 0.76109,-1.82049 0.507438,-0.49651 1.125179,-0.7448 1.85324,-0.7448 z"
+       id="path849"
+       inkscape:connector-curvature="0" />
+  </g>
+</svg>

docs/ldoc.css

@@ -25,22 +25,43 @@ hr {
 tt {
     font-family: monospace;
 }
+
 span.parameter {
     font-family: monospace;
     font-weight: bold;
     color: rgb(99, 115, 131);
 }
-span.parameter:after {
-    content:":";
+
+span.optional_param {
+    font-style: italic;
+    color: rgb(143, 166, 230);
 }
-span.types:before {
-    content:"(";
+
+.types {
+    white-space: pre;
 }
-span.types:after {
-    content:")";
+
+td span.types {
+    flex-flow: nowrap;
+    display: inline-flex;
+    width: 100%;
 }
+
+td span.inline_types {
+    color: #a4c7ff;
+    flex-flow: nowrap;
+    width: 100%;
+}
+
 .type {
-    font-weight: bold; font-style:italic
+    flex-basis: auto;
+    font-weight: bold;
+    font-style:italic;
+    pointer-events: none;
+    text-decoration: none;
+    color: #008fee;
+    text-align: center;
+    flex-grow: 1;
 }
 
 p.name {
@@ -51,7 +72,12 @@ kbd,
 p code,
 ol code,
 ul code,
-dd > code {
+dd > code,
+td code,
+span.default_value,
+.see_also_description code,
+.important_box code
+{
     background-color: #eaedf587;
     padding-left: 3px;
     padding-right: 3px;
@@ -64,15 +90,39 @@ dd > code {
     margin-right: 5px;
 }
 
+#main {
+    display: flex;
+}
+
 #navigation {
-    float: left;
+    --sidebar-width: 14em;
+    --sidebar-toggle-width: 24px;
+
     background-color: white;
     border-right: 1px solid #d3dbec;
     border-bottom: 1px solid #d3dbec;
 
-    width: 14em;
-    vertical-align: top;
+    width: var(--sidebar-width);
     overflow: visible;
+
+    margin-left: calc(-1 * var(--sidebar-width) + var(--sidebar-toggle-width));
+    transition: margin-left 0.2s ease-out;
+}
+
+#navigation.open {
+    margin-left: 0;
+}
+
+@media (hover: hover) {
+    #navigation:hover {
+        margin-left: 0;
+    }
+}
+
+@media all and (min-width: 768px) {
+    #navigation {
+        margin-left: 0;
+    }
 }
 
 #navigation br {
@@ -99,6 +149,10 @@ dd > code {
     margin-bottom: 0px;
 }
 
+#content {
+    overflow: hidden;
+}
+
 #content h1 {
     background-color: #2c3e67;
     color: white;
@@ -133,6 +187,7 @@ dd > code {
     margin-left: 15px;
     margin-bottom: 5px;
     border-bottom: solid 1px #bcd;
+    font-weight: normal;
 }
 
 #content h4 {
@@ -141,11 +196,11 @@ dd > code {
     border-bottom: solid 1px #bcd;
 }
 
-#content pre {
+#content pre, .auto_genenerated_code {
     margin: 15px;
 }
 
-pre {
+pre, .auto_genenerated_code {
     background-color: rgb(50, 55, 68);
     color: white;
     border-radius: 3px;
@@ -185,10 +240,6 @@ table.index td {
     margin: 0px 3px 0px -1em;
 }
 
-#content {
-    margin-left: 14em;
-}
-
 #content p {
     padding-left: 15px;
     padding-right: 15px;
@@ -209,6 +260,56 @@ table th, table td {
     padding: 2px;
 }
 
+.important_box {
+    padding-left: 40px;
+    min-height: 32px;
+    max-width: 640px;
+    vertical-align: middle;
+    background-image: url("images/warning_icon.svg");
+    background-size: 32px 32px;
+    background-repeat: no-repeat;
+    background-position: left center;
+    margin-top: 15px;
+    margin-bottom: 5px;
+    margin-left: 10px;
+}
+
+.see_also, .see_also td, .see_also th {
+    border-style: hidden !important;
+    padding-left: 5pt;
+    padding-right: 5pt;
+}
+
+.see_also tr td:nth-of-type(1) {
+    display: list-item;
+    list-style-type: disc;
+    list-style-position: inside;
+}
+
+.see_also tr:hover {
+    background-color: #f7fbff;
+}
+
+.see_also tr th {
+    color: rgb(168, 168, 168);
+    padding-top: 15px;
+    padding-bottom: 4px;
+    font-weight: normal;
+    text-decoration: none;
+    font-style:italic;
+    font-size: 85%;
+}
+
+.see_also_description {
+    max-width: 640px;
+}
+
+.see_also_sublist td:nth-of-type(1) {
+    margin-left: 10px;
+    padding-left: 15px;
+    border-left: 1px solid rgb(200, 200, 200) !important;
+}
+
 .widget_list td {
     padding-top: 10px;
     padding-bottom: 10px;
@@ -280,12 +381,17 @@ table th, table td {
 
 #about {
     padding: 15px;
-    padding-left: 16em;
     background-color: white;
     border-top: 1px solid #d3dbec;
     border-bottom: 1px solid #d3dbec;
 }
 
+@media all and (min-width: 768px) {
+    #about {
+        padding-left: calc(14em + 15px);
+    }
+}
+
 table.module_list, table.function_list {
     border-width: 1px;
     border-style: solid;
@@ -301,26 +407,22 @@ table.module_list td, table.function_list td {
     padding-bottom: 5px;
 }
 table.module_list td.name, table.function_list td.name {
-    background-color: white;
     min-width: 200px;
     border-left-width: 0px;
     border-right-width: 0px;
 }
 table.module_list td.summary, table.function_list td.summary {
-    background-color: white;
     width: 100%;
     border-left-width: 0px;
     border-right: none;
 }
 
 table.function_list td.shortname {
-    background-color: white;
     border-left-width: 0px;
     border-right-width: 0px;
 }
 
 table.function_list td.inheritance {
-    background-color: white;
     border-right-width: 0px;
     border-left-width: 0px;
     color: #a4c7ff;
@@ -337,8 +439,15 @@ span.inheritance {
     font-weight: normal;
 }
 
+span.not_applicable {
+    color: rgb(200, 200, 200);
+    font-style:italic;
+    font-size: 85%;
+    text-align: center;
+    display: block;
+}
+
 .summarytype {
-    background-color: white;
     color: #a4c7ff;
     font-size: 85%;
     border-left: none;
@@ -346,14 +455,18 @@ span.inheritance {
     text-align: right;
 }
 
-span.chips--readonly {
+span.chips {
   border: 1px solid #9db9f3;
   border-radius: 25px;
-  padding: 1px 3px;
-  font-size: 70%;
+  padding-left: 5pt;
+  padding-right: 5pt;
+  padding-top: 1pt;
+  padding-bottom: 1pt;
+  font-size: 85%;
   color: #9db9f3;
   background-color: #FFF;
   margin-left: 10px;
+  vertical-align: middle;
 }
 
 table.function_list .function_args /*.function_modname*/ {
@@ -382,7 +495,6 @@ table.function_list .function_named_args {
 }
 
 table.function_list td.baseclass {
-    background-color: white;
     color: #a4c7ff;
     min-width: 200px;
     border-left: none;
@@ -417,7 +529,7 @@ dl.function dd {
     margin-bottom: 15px;
 }
 
-#content dl.function dd h3 {
+#content dl.function dd h3, .see_also i {
     margin-top: 0px;
     margin-left: 0px;
     padding-left: 0px;
@@ -538,6 +650,8 @@ pre .url { color: #272fc2; text-decoration: underline; }
 /* Inheritance diagram */
 .inheritance .inheritance__level {
     list-style: none;
+    padding-top: 0px;
+    padding-left: 30px;
 }
 
 .inheritance .inheritance__level--root {
@@ -563,3 +677,81 @@ pre .url { color: #272fc2; text-decoration: underline; }
 .extra-header__section {
     flex-grow: 1;
 }
+
+.summary_row {
+    background-color: white;
+}
+
+.summary_row:hover {
+    background-color: #f7fbff;
+}
+
+/* CSS for beautiful.fg_normal */
+.svg_stroke, .svg_fill {
+    color: black;
+}
+
+#content > .components-relationship {
+    margin-left: 15px;
+    margin-right: 15px;
+}
+
+.components-relationship--diagrams {
+    display: flex;
+    flex-direction: column;
+}
+
+.components-relationship--diagram {
+    flex-grow: 1;
+    flex-basis: 100%;
+}
+
+.components-relationship--diagram > table {
+    margin: 0;
+    width: 100%;
+}
+
+.components-relationship--diagram + .components-relationship--diagram {
+    margin-top: 15px;
+}
+
+/* on wide displays, put both diagrams next to each other */
+@media all and (min-width: 1100px) {
+    .components-relationship--diagrams {
+        flex-direction: row;
+    }
+
+    .components-relationship--diagram {
+        flex-grow: 1;
+        flex-basis: 50%;
+    }
+
+    .components-relationship--diagram + .components-relationship--diagram {
+        margin-top: 0;
+        margin-left: 15px;
+    }
+}
+
+.components-relationship--legend {
+    color: #00000044;
+    margin-top: 15px;
+}
+
+.img-object {
+    max-width: 100%;
+    padding: 5px;
+}
+
+.copy-link {
+    font-size: 9px;
+    padding: 2px;
+    border-radius: 9px;
+    vertical-align: middle;
+    text-decoration: none;
+}
+.copy-link--success {
+    background-color: green;
+}
+.copy-link--failure {
+    background-color: red;
+}

docs/ldoc.ltp

@@ -24,25 +24,27 @@
 <body>
 
 <div id="container">
-
-<div id="product">
-    <div id="product_logo"></div>
-    <div id="product_name"><big><b></b></big></div>
-    <div id="product_description"></div>
-</div> <!-- id="product" -->
-
-
 <div id="main">
 
 # local no_spaces = ldoc.no_spaces
 # local use_li = ldoc.use_li
 # local display_name = ldoc.display_name
 # local iter = ldoc.modules.iter
-# local function un_cmake(s) return s:gsub("&#59", ";"):gsub("&#34", '"') end
+# local function un_cmake(s) return s:gsub("&#59", ";"):gsub("&#34", '"'):gsub('&amp;#34', '"') end
 # local function M(txt,item) return ldoc.markup(txt and un_cmake(txt) or nil,item,ldoc.plain) end
 # local nowrap = ldoc.wrap and '' or 'nowrap'
 # local html_space = function(s) return s:gsub(" ", "%%20") end
 # local no_underscores = function(s) return s:gsub("_", " ") end
+# local get_item = function(mod, name) for item in iter(mod.items) do if item.name == name then return item end end; return name == "" and mod or nil end
+
+# -- Poke a hole to allow config.ld code to have a global initialization.
+# for m in iter(ldoc.modules) do
+#    if #m.items > 0 then
+#      display_name(m.items[1])
+#      m.items[1].global_init(ldoc)
+#      break
+#    end
+# end
 
 # --------- modules hierarchy -------------
 # local hierarchy = {}
@@ -74,7 +76,7 @@
 #     local myitems = {}
 #     for item in items() do
 #       myitems[#myitems + 1] = item
-#      end
+#     end
 #     all_module_kinds[#all_module_kinds + 1] = { kind = kind,  items = myitems }
 # end
 # local filtered_kinds = { "Constructors", "Static module functions",
@@ -121,7 +123,6 @@
 <!-- Menu -->
 
 <div id="navigation">
-<br/>
 <h1>$(ldoc.project)</h1>
 
 # if not ldoc.single and module then -- reference back to project index
@@ -147,7 +148,7 @@
 # if ldoc.no_summary and module and not ldoc.one then -- bang out the functions on the side
 # for kind, items in module.kinds() do
 #  if not kind:match("^ldoc_skip") then
-<h2>$(kind)dasdasd</h2>
+<h2>$(kind)</h2>
 <ul class="nowrap">
 #  end
 # for item in items() do
@@ -180,7 +181,7 @@
 <div id="content">
 
 # if ldoc.body then -- verbatim HTML as contents; 'non-code' entries
-    $(ldoc.body)
+    $(un_cmake(ldoc.body))
 # elseif module then -- module documentation
 <h1>Module: <code>$(module.name)</code></h1>
 <p>$(M(module.summary,module))</p>
@@ -280,7 +281,7 @@
 #   local dn = display_name(item)
 #   local inherited = (item.baseclass ~= module.name)
 #   if item.sanitize_type then item.sanitize_type(item, ldoc) end
-    <tr>
+    <tr class="summary_row">
 #   if item.display_type and not item.compact_signature then
       <td class="shortname" $(nowrap)><a href="#$(item.name)">$(dn)</a></td>
       <td class="summarytype" nowrap>$(item.display_type)</td>
@@ -292,17 +293,20 @@
 #     end
       </td>
 #   end
-      <td colspan="$(inherited and 1 or 2)" class="summary">
+      <td class="summary">
         $(M(item.summary,item))
-#   if item.tags.readonly then
-        <span class="chips--readonly">read only</span>
-#   end
       </td>
-#   if inherited then
       <td class="baseclass" nowrap>
-        Inherited from $(item.baseclass)
-      </td>
+#   if item.tags.is_deprecated then
+        <span class="chips">Deprecated</span>
 #   end
+#   if item.tags.readonly then
+        <span class="chips">Read only</span>
+#   end
+#   if inherited then
+        <span class="chips">Inherited from $(item.baseclass)</span>
+#   end
+      </td>
     </tr>
 #  end end -- for items
 # last_kind = kind
@@ -345,7 +349,7 @@
 #  end
 #  for item in iter(k.items) do if not item.tags.hidden then
     <dt>
-    <a name = "$(item.name)"></a>
+    <a class="copy-link js-copy-link" name="$(item.name)" href="#$(item.name)">&#128279;</a>
     <strong>$(display_name(item))</strong>
 #   if item.display_inheritance then
     <span class="inheritance">
@@ -373,40 +377,106 @@
     <dd>
     $(M(ldoc.descript(item),item))
 
-#  if show_parms and item.params and #item.params > 0 and not item.hide_params then
+#  if kind == "Object properties" and item.params[1] and #item.metadata > 0 then
+    <h3>Constraints:</h3>
+    <span class="property_type">
+      <table class="see_also">
+#   local current_level
+#   current_level = function(metadata, level)
+#    for _, metadata in ldoc.ipairs(metadata, level) do
+       <tr class="$(level>0 and "see_also_sublist" or "")">
+        <td style="padding-left:$(level*15)px;">
+         <i>
+          $(metadata.title)$(#(metadata.metadata or {}) > 0 and ":" or "")
+         </i>
+#     if metadata.datatype then
+          <span class="inline_types"> ($(metadata.datatype))</span>
+#     end
+        </td>
+#     if metadata.description and not metadata.description:match("^[\t\n ]*$") then
+        <td>: $(metadata.description)</td>
+#     end
+       <tr/>
+#     current_level(metadata.metadata, level + 1)
+#    end
+#   end --current_level
+#   current_level(item.metadata or {}, 0)
+     </table>
+    </span>
+#  elseif show_parms and item.params and #item.params > 0 and not item.hide_params then
 #    local subnames = module.kinds:type_of(item).subnames
 #    if subnames then
     <h3>$(subnames):</h3>
 #    end
-    <ul>
+#   local has_optional, has_named_call = false, false
+#   for parm in iter(item.params) do
+#     local param,sublist = item:subparam(parm)
+#     has_named_call = has_named_call or (sublist and item.is_named_call)
+#     for p in iter(param) do
+#       local def = item:default_of_param(p)
+#       has_optional = has_optional or (def and def ~= true)
+#     end
+#   end
+#   if has_named_call then
+        <div class="important_box">
+          <b>Note:</b> This $(item.kind) uses named parameters calling convention. It
+          means you call it with $(M('`{}`')) and omit the parantheses. For example,
+          calling this will all default argument would be <code>$(item.name){}</code>.
+          This is a Lua shortcut syntax equivalent to <code>$(item.name)({})</code>.
+          <code>args</code> is only a placeholder name for the "lone table argument"
+          used in named parameters calls.
+        </div>
+#   end
+    <table class="see_also">
+         <tr class="param_header">
+            <th>Name</th>
+            <th></th>
+            <th>Type(s)</th>
+            <th>Description</th>
+#   if has_optional then
+            <th>Default value</th>
+#   end
+         </tr>
 #   for parm in iter(item.params) do
 #     local param,sublist = item:subparam(parm)
 #     if sublist then
-        <li><span class="parameter">$(sublist)</span>$(M(item.params.map[sublist],item))
-        <ul>
+#       local def = item:default_of_param(sublist)
+        <tr>
+           <td><span class="parameter">$(sublist)</span></td>
+           <td>$(def and '<span class="chips">Optional</span>' or '')</td>
+           <td><span class="types"><span class="type">table</span></span></td>
+           <td class="see_also_description">$(M(item.params.map[sublist],item)) </td>
+#      if has_optional then
+#       if def and def ~= true then
+          <td><span class="default_value"><code>$(def)</code></span></td>
+#       elseif def then
+           <td><span class="not_applicable">Undefined</span></td>
+#       else
+           <td><span class="not_applicable" title="This parameter is mandatory">Not applicable</span></td>
+#       end
+#      end
+         </tr>
 #     end
 #     for p in iter(param) do
 #        local name,tp,def = item:display_name_of(p), ldoc.typename(item:type_of_param(p)), item:default_of_param(p)
-        <li><span class="parameter">$(name)</span>
-#       if tp ~= '' then
-            <span class="types">$(tp)</span>
+         <tr$(sublist and ' class="see_also_sublist"' or '')>
+           <td><span class="parameter">$(name)</span></td>
+           <td>$(def and '<span class="chips">Optional</span>' or '')</td>
+           <td><span class="types">$(tp)</span></td>
+           <td class="see_also_description">$(M(item.params.map[p],item))</td>
+#      if has_optional then
+#       if def and def ~= true then
+           <td><span class="default_value"><code>$(def)</code></span></td>
+#       elseif def then
+           <td><span class="not_applicable">Undefined</span></td>
+#       else
+           <td><span class="not_applicable" title="This parameter is mandatory">Not applicable</span></td>
 #       end
-        $(M(item.params.map[p],item))
-#       if def == true then
-         (<em>optional</em>)
-#      elseif def then
-         (<em>default</em> <code>$(def)</code>)
-#       end
-#       if item:readonly(p) then
-          <em>readonly</em>
-#       end
-        </li>
-#     end
-#     if sublist then
-        </li></ul>
+#      end
+         </tr>
 #     end
 #   end -- for
-    </ul>
+        </table>
 #   end -- if params
 
 #  if show_return and item.retgroups then local groups = item.retgroups
@@ -444,11 +514,21 @@
 #   if item.see then
 #     local li,il = use_li(item.see)
     <h3>See also:</h3>
-    <ul>
-#     for see in iter(item.see) do
-         $(li)<a href="$(ldoc.href(see))">$(see.label)</a>$(il)
+    <table class="see_also">
+#    for see in iter(item.see) do
+#      local see_item = see.mod and get_item(see.mod, see.name)
+#      local see_mod = (see_item and see.mod and see.mod ~= item.module and see.mod.name ~= see_item.name) and "("..see.mod.name..")" or ""
+     <tr>
+         <td><a href="$(ldoc.href(see))" title="In the $(see.mod and see.mod.name) module.">$(see.label)</a></td>
+         <td>$(see_item and M(see_item.summary)) $(see_mod)</td>
+         <td>
+#       if see_item or see.name == "" then
+             <span class="chips">$(see.name == "" and "module" or (see_item and see_item.kind))</span>
+#       end
+         </td>
+     <tr>
 #    end -- for
-    </ul>
+    </table>
 #   end -- if see
 
 #   if item.usage then
@@ -487,7 +567,7 @@
 #       end -- if group_header then
 #       for value in iter(tag) do
           <$(row_type_begin)>$(custom.format and custom.format(value, item, M) or M(value))</$(row_type_end)>
-#         local sub_values, sub_custom = item.get_auto_params(custom[1], value)
+#         local sub_values, sub_custom, extra_data = item.get_auto_params(custom[1], value)
 #         if sub_values then
            <ul>
 #          for _, value in ldoc.ipairs(sub_values) do
@@ -495,6 +575,12 @@
 #          end -- for auto_params
            </ul>
 #         end -- if item.auto_params
+#          if extra_data.usage then
+           <br/>
+           <p>
+           <pre class="auto_genenerated_code">$(extra_data.usage)</pre>
+#          end -- extra_data.usage
+
 #       end -- for
      </$(group_end)>
 #      end -- if tag
@@ -537,5 +623,78 @@
 <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc $(ldoc.version)</a></i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
+
+<script defer type="text/javascript">
+    const $nav = document.querySelector("#navigation");
+
+    // When clicking the sidebar, open it
+    $nav.addEventListener("click", function(ev) {
+        if (document.body.clientWidth >= 768) {
+            return;
+        }
+
+        const target = $nav;
+        if (!target.classList.contains("open")) {
+            target.classList.add("open");
+            ev.stopPropagation();
+        }
+    });
+
+    // When clicking anywhere else than the sidebar, close it
+    document.querySelector("body").addEventListener("click", function(ev) {
+        if (document.body.clientWidth >= 768 || ev.target.contains($nav)) {
+            return;
+        }
+
+        const target = $nav;
+        if (target.classList.contains("open")) {
+            target.classList.remove("open");
+        }
+    });
+
+    const copyResultClasses = {
+        success : "copy-link--success",
+        failure: "copy-link--failure"
+    };
+
+    const removeCopyResultClasses = ($target) =>
+        Object.values(copyResultClasses).forEach(c => $target.classList.remove(c));
+
+    document.querySelectorAll(".js-copy-link").forEach(copyLink => {
+        copyLink.addEventListener("click", function(e) {
+            e.preventDefault();
+            const $target = e.target;
+
+            removeCopyResultClasses($target);
+
+            let link = $target.href;
+            if (!link) {
+                return;
+            }
+            if (link.startsWith("#")) {
+                const curr = window.location.pathname;
+                link = curr.substring(0, curr.indexOf("#")) + link;
+            }
+
+            // We need to create a fake element to copy the text from
+            const fakeElement = document.createElement("textarea");
+            fakeElement.value = link;
+            document.body.appendChild(fakeElement);
+            fakeElement.select();
+
+            let success = false;
+            try {
+                success = document.execCommand("copy");
+            } catch(err) {
+                success = false;
+            }
+
+            fakeElement.remove();
+            $target.classList.add(success ? copyResultClasses.success : copyResultClasses.failure);
+            setInterval(() => removeCopyResultClasses($target), 1500);
+        });
+    });
+</script>
+
 </body>
 </html>

lib/awful/button.lua

@@ -70,41 +70,51 @@ button.names = {
 -- Please note that Awesome ignores the status of "Lock" and "Mod2" (Num Lock).
 --
 -- @property modifiers
+-- @tparam[opt={}] table modifiers
+-- @tablerowtype A list of modifier names in no specific order.
 
 --- The mouse button identifier.
 --
 -- ![Mouse buttons](../images/mouse.svg)
 --
 -- @property button
--- @param integer
+-- @tparam integer button
+-- @propertydefault Set in the constructor.
+-- @propertyunit X11 mouse button codes.
+-- @negativeallowed false
 
 --- The button description.
 --
 -- @property description
--- @param string
+-- @tparam[opt=""] string description
 
 --- The button name.
 --
 -- @property name
--- @param string
+-- @tparam[opt=""] string name
 
 --- The button group.
 --
 -- @property group
--- @param string
+-- @tparam[opt=""] string group
 
 --- The callback when this button is pressed.
 --
 -- @property on_press
--- @param function
+-- @tparam[opt=nil] function|nil on_press
+-- @functionnoparam
+-- @functionnoreturn
 
 --- The callback when this button is released.
 --
 -- @property on_release
--- @param function
+-- @tparam[opt=nil] function|nil on_release
+-- @functionnoparam
+-- @functionnoreturn
 
 --- Execute this mousebinding.
--- @method :trigger
+-- @method trigger
+-- @noreturn
 
 function button:set_button(b)
     for _, v in ipairs(self) do
@@ -237,7 +247,7 @@ local obj_mt = {
 --
 -- @constructorfct awful.button
 -- @tparam table mod A list of modifier keys.  Valid modifiers are:
---  `Any`, `Mod1`, Mod2`, `Mod3`, `Mod4`, `Mod5`, `Shift`, `Lock` and `Control`.
+--  `Any`, `Mod1`, `Mod2`, `Mod3`, `Mod4`, `Mod5`, `Shift`, `Lock` and `Control`.
 --  This argument is (**mandatory**).
 -- @tparam number button The mouse button (it is recommended to use the
 --  `awful.button.names` constants.
@@ -250,7 +260,7 @@ local obj_mt = {
 -- @constructorfct2 awful.button
 -- @tparam table args
 -- @tparam table args.modifiers A list of modifier keys.  Valid modifiers are:
---  `Any`, `Mod1`, Mod2`, `Mod3`, `Mod4`, `Mod5`, `Shift`, `Lock` and `Control`.
+--  `Any`, `Mod1`, `Mod2`, `Mod3`, `Mod4`, `Mod5`, `Shift`, `Lock` and `Control`.
 --  This argument is (**mandatory**).
 -- @tparam number args.button The mouse button (it is recommended to use the
 --  `awful.button.names` constants.

lib/awful/client.lua

@@ -157,7 +157,7 @@ client.focus = require("awful.client.focus")
 --
 -- @deprecated awful.client.jumpto
 -- @see client.jump_to
--- @tparam client c the client to jump to
+-- @tparam client c The client to jump to
 -- @tparam bool|function merge If true then merge tags (select the client's
 --   first tag additionally) when the client is not visible.
 --   If it is a function, it will be called with the client and its first
@@ -174,10 +174,11 @@ end
 -- @DOC_sequences_client_jump_to1_EXAMPLE@
 --
 -- @method jump_to
--- @tparam bool|function merge If true then merge tags (select the client's
+-- @tparam[opt] bool|function merge If true then merge tags (select the client's
 --   first tag additionally) when the client is not visible.
 --   If it is a function, it will be called with the client and its first
 --   tag as arguments.
+-- @noreturn
 -- @request client activate client.jumpto granted When a client is activated
 --  because `c:jump_to()` is called.
 -- @see activate
@@ -212,7 +213,7 @@ end
 --
 -- @deprecated awful.client.visible
 -- @see screen.clients
--- @tparam[opt] integer|screen s The screen, or nil for all screens.
+-- @tparam[opt] nil|integer|screen s The screen, or nil for all screens.
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
 -- @treturn table A table with all visible clients.
 function client.visible(s, stacked)
@@ -230,7 +231,7 @@ end
 --
 -- @deprecated awful.client.tiled
 -- @see screen.tiled_clients
--- @tparam integer|screen s The screen, or nil for all screens.
+-- @tparam nil|integer|screen s The screen, or nil for all screens.
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
 -- @treturn table A table with all visible and tiled clients.
 function client.tiled(s, stacked)
@@ -253,8 +254,8 @@ end
 -- If no client is passed, the focused client will be used.
 --
 -- @staticfct awful.client.next
--- @tparam int i The index.  Use 1 to get the next, -1 to get the previous.
--- @tparam[opt] client sel The client.
+-- @tparam int i The index.  Use `1` to get the next, `-1` to get the previous.
+-- @tparam[opt=client.focus] client sel The client.
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
 -- @treturn[opt] client|nil A client, or nil if no client is available.
 -- @see client.get
@@ -296,8 +297,9 @@ end
 --
 -- @staticfct awful.client.swap.bydirection
 -- @tparam string dir The direction, can be either "up", "down", "left" or "right".
--- @tparam[opt=focused] client c The client.
+-- @tparam[opt="focused"] client c The client.
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
+-- @noreturn
 -- @see swap
 -- @see swapped
 -- @see awful.client.swap.global_bydirection
@@ -328,7 +330,8 @@ end
 --
 -- @staticfct awful.client.swap.global_bydirection
 -- @tparam string dir The direction, can be either "up", "down", "left" or "right".
--- @tparam[opt] client sel The client.
+-- @tparam[opt=client.focus] client sel The client.
+-- @noreturn
 -- @request client activate client.swap.global_bydirection granted When a client
 --  could be activated because `awful.client.swap.global_bydirection` was called.
 -- @see swap
@@ -370,13 +373,15 @@ end
 -- @DOC_sequences_client_swap_byidx1_EXAMPLE@
 --
 -- @staticfct awful.client.swap.byidx
--- @tparam integer i The index.
--- @tparam[opt] client c The client, otherwise focused one is used.
+-- @tparam integer i The index. Use `1` to get the next, `-1` to get the previous.
+-- @tparam[opt=client.focus] client c The client, otherwise focused one is used.
+-- @noreturn
 -- @see swap
 -- @see swapped
 -- @see awful.client.swap.bydirection
 -- @see awful.client.swap.global_bydirection
 -- @see awful.client.cycle
+-- @see awful.client.next
 function client.swap.byidx(i, c)
     local sel = c or capi.client.focus
     local target = client.next(i, sel)
@@ -393,9 +398,10 @@ end
 -- @DOC_sequences_client_cycle1_EXAMPLE@
 --
 -- @staticfct awful.client.cycle
--- @tparam boolean clockwise True to cycle clients clockwise.
--- @tparam[opt] screen s The screen where to cycle clients.
+-- @tparam[opt=false] boolean clockwise True to cycle clients clockwise.
+-- @tparam[opt=awful.screen.focused()] screen s The screen where to cycle clients.
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
+-- @noreturn
 -- @see swap
 -- @see swapped
 -- @see awful.client.swap.bydirection
@@ -423,6 +429,7 @@ end
 --
 -- @method append_keybinding
 -- @tparam awful.key key The key.
+-- @noreturn
 -- @see remove_keybinding
 -- @see append_mousebinding
 -- @see remove_mousebinding
@@ -430,17 +437,20 @@ end
 --- Remove a keybinding.
 --
 -- @method remove_keybinding
+-- @noreturn
 -- @tparam awful.key key The key.
 
 --- Append a mousebinding.
 --
 -- @method append_mousebinding
 -- @tparam awful.button button The button.
+-- @noreturn
 
 --- Remove a mousebinding.
 --
 -- @method remove_mousebinding
 -- @tparam awful.button button The button.
+-- @noreturn
 
 --- Get the master window.
 --
@@ -475,6 +485,7 @@ end
 -- @DOC_sequences_client_to_primary_EXAMPLE@
 --
 -- @method to_primary_section
+-- @noreturn
 -- @see swap
 -- @see to_secondary_section
 function client.object:to_primary_section()
@@ -493,6 +504,7 @@ end
 -- @DOC_sequences_client_to_secondary_EXAMPLE@
 --
 -- @method to_secondary_section
+-- @noreturn
 -- @see swap
 -- @see to_primary_section
 
@@ -510,7 +522,7 @@ end
 -- @tparam integer y The relative y coordinate.
 -- @tparam integer w The relative width.
 -- @tparam integer h The relative height.
--- @tparam[opt] client c The client, otherwise focused one is used.
+-- @tparam[opt=client.focus] client c The client, otherwise focused one is used.
 -- @see client.relative_move
 function client.moveresize(x, y, w, h, c)
     gdebug.deprecate("Use c:relative_move(x, y, w, h) instead of awful.client.moveresize", {deprecated_in=4})
@@ -522,11 +534,17 @@ end
 -- @DOC_sequences_client_relative_move1_EXAMPLE@
 --
 -- @method relative_move
+-- @tparam[opt=0] integer x The relative x coordinate.
+-- @tparam[opt=0] integer y The relative y coordinate.
+-- @tparam[opt=0] integer w The relative width.
+-- @tparam[opt=0] integer h The relative height.
+-- @noreturn
 -- @see geometry
--- @tparam[opt=0] number x The relative x coordinate.
--- @tparam[opt=0] number y The relative y coordinate.
--- @tparam[opt=0] number w The relative width.
--- @tparam[opt=0] number h The relative height.
+-- @see x
+-- @see y
+-- @see width
+-- @see height
+-- @see floating
 function client.object.relative_move(self, x, y, w, h)
     local geometry = self:geometry()
     geometry['x'] = geometry['x'] + (x or 0)
@@ -552,6 +570,7 @@ end
 --
 -- @method move_to_tag
 -- @tparam tag target The tag to move the client to.
+-- @noreturn
 -- @request client activate client.movetotag granted When a client could be
 --  activated because `c:move_to_tag()` was called.
 -- @see tags
@@ -571,7 +590,7 @@ end
 --
 -- @deprecated awful.client.toggletag
 -- @tparam tag target The tag to toggle.
--- @tparam[opt] client c The client to toggle, otherwise the focused one is used.
+-- @tparam[opt=client.focus] client c The client to toggle, otherwise the focused one is used.
 -- @see client.toggle_tag
 -- @see tags
 function client.toggletag(target, c)
@@ -585,6 +604,7 @@ end
 --
 -- @method toggle_tag
 -- @tparam tag target The tag to move the client to.
+-- @noreturn
 -- @see tags
 function client.object.toggle_tag(self, target)
     -- Check that tag and client screen are identical
@@ -610,7 +630,7 @@ end
 
 --- Move a client to a screen. Default is next screen, cycling.
 -- @deprecated awful.client.movetoscreen
--- @tparam client c The client to move.
+-- @tparam[opt=client.focus] client c The client to move.
 -- @tparam screen s The screen, default to current + 1.
 -- @see screen
 -- @see client.move_to_screen
@@ -625,6 +645,7 @@ end
 --
 -- @method move_to_screen
 -- @tparam[opt=c.screen.index+1] screen s The screen, default to current + 1.
+-- @noreturn
 -- @see screen
 -- @see request::activate
 -- @request client activate client.movetoscreen granted When a client could be
@@ -676,6 +697,7 @@ end
 -- @DOC_sequences_client_to_selected_tags1_EXAMPLE@
 --
 -- @method to_selected_tags
+-- @noreturn
 -- @see screen.selected_tags
 function client.object.to_selected_tags(self)
     local tags = {}
@@ -709,7 +731,7 @@ end
 --- If a client is marked or not.
 --
 -- @property marked
--- @tparam boolean marked
+-- @tparam[opt=false] boolean marked
 -- @emits marked (for legacy reasons, use `property::marked`)
 -- @emits unmarker (for legacy reasons, use `property::marked`)
 -- @emits property::marked
@@ -791,16 +813,27 @@ end
 -- Floating client are not handled by tiling layouts.
 -- @deprecated awful.client.floating.set
 -- @tparam client c A client.
--- @tparam boolean s True or false.
+-- @tparam boolean s `true` is the client is to become floating or `false`.
 function client.floating.set(c, s)
     gdebug.deprecate("Use c.floating = true instead of awful.client.floating.set", {deprecated_in=4})
     client.object.set_floating(c, s)
 end
 
 -- Set a client floating state, overriding auto-detection.
--- Floating client are not handled by tiling layouts.
+--
+-- Floating client are not handled by tiling layouts. They can be
+-- moved around and resized freely unless other restriction, such as `maximized`
+-- or the `size_hints` restrict their geometry.
+--
+-- An easy way to position floating clients is to use the `awful.placement`
+-- module.
+--
 -- @tparam client c A client.
--- @tparam boolan s True or false.
+-- @tparam boolean floating.
+-- @see is_immobilized_vertical
+-- @see is_immobilized_horizontal
+-- @see is_fixed
+-- @see size_hints
 function client.object.set_floating(c, s)
     c = c or capi.client.focus
     if c and client.property.get(c, "floating") ~= s then
@@ -838,7 +871,7 @@ capi.client.connect_signal("property::geometry", store_floating_geometry)
 
 --- Return if a client has a fixed size or not.
 -- This function is deprecated, use `c.is_fixed`
--- @tparam client c The client.
+-- @tparam[opt=client.focus] client c The client.
 -- @deprecated awful.client.isfixed
 -- @see is_fixed
 -- @see size_hints_honor
@@ -850,8 +883,10 @@ end
 
 --- Return if a client has a fixed size or not.
 --
+-- Fixed size means it cannot be resized.
+--
 -- @property is_fixed
--- @tparam[opt=false] boolean is_fixed The fixed size state
+-- @tparam[opt=false] boolean is_fixed
 -- @propemits false false
 -- @readonly
 -- @see size_hints
@@ -874,10 +909,10 @@ end
 --- Is the client immobilized horizontally?
 --
 -- Does the client have a fixed horizontal position and width, i.e. is it
--- fullscreen, maximized, or horizontally maximized?
+-- `fullscreen`, `maximized`, or `maximized_horizontal`?
 --
 -- @property immobilized_horizontal
--- @tparam[opt=false] boolean immobilized_horizontal The immobilized state
+-- @tparam[opt=false] boolean immobilized_horizontal
 -- @readonly
 -- @see maximized
 -- @see maximized_horizontal
@@ -893,7 +928,7 @@ end
 -- fullscreen, maximized, or vertically maximized?
 --
 -- @property immobilized_vertical
--- @tparam[opt=false] boolean immobilized_vertical The immobilized state
+-- @tparam[opt=false] boolean immobilized_vertical
 -- @readonly
 -- @see maximized
 -- @see maximized_vertical
@@ -926,7 +961,7 @@ end
 -- @DOC_sequences_client_floating1_EXAMPLE@
 --
 -- @property floating
--- @tparam boolean floating The floating state.
+-- @tparam[opt=false] boolean floating
 -- @request client border floating granted When a border update is required
 --  because the client focus status changed.
 -- @request client border active granted When a client becomes active and is not
@@ -1014,7 +1049,8 @@ end
 -- @DOC_sequences_client_x1_EXAMPLE@
 --
 -- @property x
--- @tparam integer x
+-- @tparam[opt=c:geometry().x] integer x
+-- @negativeallowed true
 -- @emits property::geometry
 -- @emitstparam property::geometry table geo The
 --  geometry (with `x`, `y`, `width`, `height`).
@@ -1032,7 +1068,8 @@ end
 -- @DOC_sequences_client_y1_EXAMPLE@
 --
 -- @property y
--- @tparam integer y
+-- @tparam[opt=c:geometry().y] integer y
+-- @negativeallowed true
 -- @emits property::geometry
 -- @emitstparam property::geometry table geo The
 --  geometry (with `x`, `y`, `width`, `height`).
@@ -1046,7 +1083,8 @@ end
 -- @DOC_sequences_client_width1_EXAMPLE@
 --
 -- @property width
--- @tparam integer width
+-- @tparam[opt=c:geometry().width] integer width
+-- @rangestart 1
 -- @emits property::geometry
 -- @emitstparam property::geometry table geo The
 --  geometry (with `x`, `y`, `width`, `height`).
@@ -1060,7 +1098,8 @@ end
 -- @DOC_sequences_client_height1_EXAMPLE@
 --
 -- @property height
--- @tparam integer height
+-- @tparam[opt=c:geometry().height] integer height
+-- @rangestart 1
 -- @emits property::geometry
 -- @emitstparam property::geometry table geo The
 --  geometry (with `x`, `y`, `width`, `height`).
@@ -1136,7 +1175,7 @@ end
 -- @DOC_screen_wfact4_EXAMPLE@
 --
 -- @legacylayout awful.client.idx
--- @tparam client c the client
+-- @tparam client c The client
 -- @treturn table data A table with "col", "idx" and "num" keys.
 -- @treturn integer data.col The column number.
 -- @treturn integer data.idx Index of the client in the column.
@@ -1207,8 +1246,8 @@ end
 -- @DOC_screen_wfact3_EXAMPLE@
 --
 -- @legacylayout awful.client.setwfact
--- @tparam number wfact the window factor value
--- @tparam client c the client
+-- @tparam number wfact The window factor value
+-- @tparam client c The client
 -- @emits property::windowfact Emitted on the c.first_tag object.
 -- @see tag.master_width_factor
 function client.setwfact(wfact, c)
@@ -1274,7 +1313,7 @@ end
 -- @tparam number add Amount to increase/decrease the client's window factor by.
 --   Should be between `-current_window_factor` and something close to
 --   infinite. Normalisation then ensures that the sum of all factors is 1.
--- @tparam client c the client.
+-- @tparam[opt=client.focus] client c The client.
 -- @emits property::windowfact
 function client.incwfact(add, c)
     c = c or capi.client.focus
@@ -1314,7 +1353,7 @@ end
 -- default.
 --
 -- @property dockable
--- @tparam boolean dockable The dockable state
+-- @tparam[opt=false] boolean dockable
 -- @propemits false false
 -- @see struts
 
@@ -1353,7 +1392,7 @@ end
 -- interprets it as the client (not) wanting a titlebar.
 --
 -- @property requests_no_titlebar
--- @tparam boolean requests_no_titlebar Whether the client
+-- @tparam[opt=false] boolean requests_no_titlebar Whether the client
 --  requests not to get a titlebar.
 -- @propemits false false
 
@@ -1427,6 +1466,7 @@ end
 -- @tparam string prop The property name.
 -- @tparam string kind The type (used for register_xproperty).
 --   One of "string", "number" or "boolean".
+-- @noreturn
 function client.property.persist(prop, kind)
     local xprop = "awful.client.property." .. prop
     capi.awesome.register_xproperty(xprop, kind)
@@ -1445,11 +1485,11 @@ end
 -- Starting from the client in focus or the given index, all clients that match
 -- a given criteria.
 --
--- @tparam function filter a function that returns true to indicate a positive match.
--- @tparam integer start  what index to start iterating from.  Defaults to using the
+-- @tparam function filter A function that returns true to indicate a positive match.
+-- @tparam integer start What index to start iterating from.  Defaults to using the
 --   index of the currently focused client.
--- @tparam screen s which screen to use.  nil means all screens.
---
+-- @tparam[opt=nil] screen s Which screen to use.  nil means all screens.
+-- @treturn function A Lua iterator (to use in a `for` loop).
 -- @staticfct awful.client.iterate
 -- @usage -- un-minimize all urxvt instances
 -- local urxvt = function (c)
@@ -1470,8 +1510,8 @@ end
 -- If multiple clients match the given condition then the next one is
 -- focused.
 --
--- @tparam string cmd the command to execute
--- @tparam function matcher a function that returns true to indicate a matching client
+-- @tparam string cmd The command to execute
+-- @tparam function matcher A function that returns true to indicate a matching client
 -- @tparam bool|function merge If true then merge tags (select the client's
 --   first tag additionally) when the client is not visible.
 --   If it is a function, it will be called with the client as argument.
@@ -1594,7 +1634,7 @@ end, true, true, "keybinding")
 -- @DOC_awful_client_shape1_EXAMPLE@
 --
 -- @property shape
--- @tparam gears.shape A gears.shape compatible function.
+-- @tparam[opt=gears.shape.rectangle] shape shape A gears.shape compatible function.
 -- @propemits true false
 -- @see gears.shape
 function client.object.set_shape(self, shape)
@@ -1640,7 +1680,7 @@ end
 --
 -- @method activate
 -- @tparam table args
--- @tparam[opt=other] string args.context Why was this activate called?
+-- @tparam[opt="other"] string args.context Why was this activate called?
 -- @tparam[opt=true] boolean args.raise Raise the client to the top of its layer
 --  and unminimize it (if needed).
 -- @tparam[opt=false] boolean args.force Force the activation even for unfocusable
@@ -1649,6 +1689,9 @@ end
 -- @tparam[opt=false] boolean args.switch_to_tag
 -- @tparam[opt=false] boolean args.action Once activated, perform an action.
 -- @tparam[opt=false] boolean args.toggle_minimization
+-- @noreturn
+-- @request client activate args.context granted Will use the context defined in
+--  `args.context`.
 -- @see awful.permissions.add_activate_filter
 -- @see awful.permissions.activate
 -- @see request::activate
@@ -1693,6 +1736,7 @@ end
 -- @method grant
 -- @tparam string permission The permission name (just the name, no `request::`).
 -- @tparam string context The reason why this permission is requested.
+-- @noreturn
 -- @see awful.permissions
 
 --- Deny a permission for a client.
@@ -1700,6 +1744,7 @@ end
 -- @method deny
 -- @tparam string permission The permission name (just the name, no `request::`).
 -- @tparam string context The reason why this permission is requested.
+-- @noreturn
 -- @see awful.permissions
 
 pcommon.setup_grant(client.object, "client")
@@ -1755,7 +1800,7 @@ pcommon.setup_grant(client.object, "client")
 --    end)
 --
 -- @property active
--- @tparam boolean active
+-- @tparam[opt=true] boolean active
 -- @request client border active granted When a client becomes active.
 -- @request client border inactive granted When a client stop being active.
 -- @readonly
@@ -1792,6 +1837,7 @@ end)
 
 --- Emitted when a client need to get a titlebar.
 -- @signal request::titlebars
+-- @tparam client c The client.
 -- @tparam[opt=nil] string content The context (like "rules")
 -- @tparam[opt=nil] table hints Some hints.
 -- @classsignal
@@ -1815,6 +1861,7 @@ end)
 -- * **floating**: When the floating or maximization state changes.
 --
 -- @signal request::border
+-- @tparam client c The client.
 -- @tparam string context The context.
 -- @tparam table hints The hints.
 -- @classsignal
@@ -1828,6 +1875,7 @@ end)
 -- @tparam bool|function merge If true then merge tags (select the client's
 --   first tag additionally) when the client is not visible.
 --   If it is a function, it will be called with the client as argument.
+-- @noreturn
 
 -- Add clients during startup to focus history.
 -- This used to happen through permissions.activate, but that only handles visible

lib/awful/completion.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- Completion module.
+--- Helper utilities for bash-like completion lists.
 --
 -- This module store a set of function using shell to complete commands name.
 --
@@ -31,7 +31,8 @@ local bashcomp_src = "@SYSCONFDIR@/bash_completion"
 
 --- Enable programmable bash completion in awful.completion.bash at the price of
 -- a slight overhead.
--- @param src The bash completion source file, /etc/bash_completion by default.
+-- @tparam string src The bash completion source file, `/etc/bash_completion` by default.
+-- @noreturn
 -- @staticfct awful.completion.bashcomp_load
 function completion.bashcomp_load(src)
     if src then bashcomp_src = src end
@@ -189,11 +190,13 @@ end
 --- Run a generic completion.
 -- For this function to run properly the awful.completion.keyword table should
 -- be fed up with all keywords. The completion is run against these keywords.
--- @param text The current text the user had typed yet.
--- @param cur_pos The current cursor position.
--- @param ncomp The number of yet requested completion using current text.
--- @param keywords The keywords table uised for completion.
--- @return The new match, the new cursor position, the table of all matches.
+-- @tparam string text The current text the user had typed yet.
+-- @tparam number cur_pos The current cursor position.
+-- @tparam number ncomp The number of yet requested completion using current text.
+-- @tparam table keywords The keywords table uised for completion.
+-- @treturn string The new match.
+-- @treturn number The new cursor position.
+-- @treturn table The table of all matches.
 -- @staticfct awful.completion.generic
 function completion.generic(text, cur_pos, ncomp, keywords) -- luacheck: no unused args
     -- The keywords table may be empty

lib/awful/hotkeys_popup/init.lua

@@ -10,7 +10,7 @@ local hotkeys_popup = {
   widget = require("awful.hotkeys_popup.widget"),
 }
 
---- This is the same as awful.hotkeys_popup.widget.show_help.
+--- This is the same as `awful.hotkeys_popup.widget.show_help`.
 --
 -- example usage:
 --
@@ -25,6 +25,7 @@ local hotkeys_popup = {
 -- @tparam[opt=true] boolean show_args.show_awesome_keys Show AwesomeWM hotkeys.
 -- When set to `false` only app-specific hotkeys will be shown.
 -- @staticfct awful.hotkeys_popup.show_help
+-- @noreturn
 -- @see awful.hotkeys_popup.widget.show_help
 
 hotkeys_popup.show_help = hotkeys_popup.widget.show_help

lib/awful/hotkeys_popup/widget.lua

@@ -74,6 +74,7 @@ local gtable = require("gears.table")
 local gstring = require("gears.string")
 local wibox = require("wibox")
 local beautiful = require("beautiful")
+local rgba = require("gears.color").to_rgba_string
 local dpi = beautiful.xresources.apply_dpi
 
 local matcher = require("gears.matcher")()
@@ -86,11 +87,11 @@ function markup.font(font, text)
 end
 -- Set the foreground.
 function markup.fg(color, text)
-    return '<span foreground="' .. tostring(color) .. '">' .. tostring(text) .. '</span>'
+    return '<span foreground="' .. rgba(color, beautiful.fg_normal) .. '">' .. tostring(text) .. '</span>'
 end
 -- Set the background.
 function markup.bg(color, text)
-    return '<span background="' .. tostring(color) .. '">' .. tostring(text) .. '</span>'
+    return '<span background="' .. rgba(color, beautiful.bg_normal) .. '">' .. tostring(text) .. '</span>'
 end
 
 local function join_plus_sort(modifiers)
@@ -124,8 +125,51 @@ widget.hide_without_description = true
 widget.merge_duplicates = true
 
 --- Labels used for displaying human-readable keynames.
--- @tfield table widget.labels
--- @param table
+-- @tfield table awful.hotkeys_popup.widget.labels
+-- @tfield[opt="Ctrl"] string Control
+-- @tfield[opt="Alt"] string Mod1
+-- @tfield[opt="Alt Gr"] string ISO_Level3_Shift
+-- @tfield[opt="Super"] string Mod4
+-- @tfield[opt="Ins"] string Insert
+-- @tfield[opt="Del"] string Delete
+-- @tfield[opt="PgDn"] string Next
+-- @tfield[opt="PgUp"] string Prior
+-- @tfield[opt="←"] string Left
+-- @tfield[opt="↑"] string Up
+-- @tfield[opt="→"] string Right
+-- @tfield[opt="↓"] string Down
+-- @tfield[opt="Num1"] string KP_End
+-- @tfield[opt="Num2"] string KP_Down
+-- @tfield[opt="Num3"] string KP_Next
+-- @tfield[opt="Num4"] string KP_Left
+-- @tfield[opt="Num5"] string KP_Begin
+-- @tfield[opt="Num6"] string KP_Right
+-- @tfield[opt="Num7"] string KP_Home
+-- @tfield[opt="Num8"] string KP_Up
+-- @tfield[opt="Num9"] string KP_Prior
+-- @tfield[opt="Num0"] string KP_Insert
+-- @tfield[opt="Num."] string KP_Delete
+-- @tfield[opt="Num/"] string KP_Divide
+-- @tfield[opt="Num*"] string KP_Multiply
+-- @tfield[opt="Num-"] string KP_Subtract
+-- @tfield[opt="Num+"] string KP_Add
+-- @tfield[opt="NumEnter"] string KP_Enter
+-- @tfield[opt="Esc"] string Escape
+-- @tfield[opt="Tab"] string Tab
+-- @tfield[opt="Space"] string space
+-- @tfield[opt="Enter"] string Return
+-- @tfield[opt="´"] string dead_acute
+-- @tfield[opt="^"] string dead_circumflex
+-- @tfield[opt="`"] string dead_grave
+-- @tfield[opt="🔆+"] string XF86MonBrightnessUp
+-- @tfield[opt="🔅-"] string XF86MonBrightnessDown
+-- @tfield[opt="🕩+"] string XF86AudioRaiseVolume
+-- @tfield[opt="🕩-"] string XF86AudioLowerVolume
+-- @tfield[opt="🔇"] string XF86AudioMute
+-- @tfield[opt="⏯"] string XF86AudioPlay
+-- @tfield[opt="⏮"] string XF86AudioPrev
+-- @tfield[opt="⏭"] string XF86AudioNext
+-- @tfield[opt="⏹"] string XF86AudioStop
 widget.labels = {
     Control          = "Ctrl",
     Mod1             = "Alt",
@@ -248,6 +292,21 @@ widget.labels = {
 -- @tparam[opt] table args.group_rules Rules for showing 3rd-party hotkeys. @see `awful.hotkeys_popup.keys.vim`.
 -- @return Widget instance.
 -- @constructorfct awful.widget.hotkeys_popup.widget.new
+-- @usebeautiful beautiful.hotkeys_fg
+-- @usebeautiful beautiful.hotkeys_bg
+-- @usebeautiful beautiful.hotkeys_border_width
+-- @usebeautiful beautiful.hotkeys_border_color
+-- @usebeautiful beautiful.hotkeys_shape
+-- @usebeautiful beautiful.hotkeys_modifiers_fg
+-- @usebeautiful beautiful.hotkeys_label_bg
+-- @usebeautiful beautiful.hotkeys_label_fg
+-- @usebeautiful beautiful.hotkeys_font
+-- @usebeautiful beautiful.hotkeys_description_font
+-- @usebeautiful beautiful.hotkeys_group_margin
+-- @usebeautiful beautiful.bg_normal Fallback.
+-- @usebeautiful beautiful.fg_normal Fallback.
+-- @usebeautiful beautiful.fg_minimize Fallback.
+-- @usebeautiful beautiful.border_width Fallback.
 function widget.new(args)
     args = args or {}
     local widget_instance = {
@@ -669,11 +728,13 @@ function widget.new(args)
 
 
     --- Show popup with hotkeys help.
-    -- @tparam[opt] client c Client.
-    -- @tparam[opt] screen s Screen.
-    -- @tparam[opt] table show_args Additional arguments.
+    -- @tparam[opt=client.focus] client c Client.
+    -- @tparam[opt=c.screen] screen s Screen.
+    -- @tparam[opt={}] table show_args Additional arguments.
     -- @tparam[opt=true] boolean show_args.show_awesome_keys Show AwesomeWM hotkeys.
     -- When set to `false` only app-specific hotkeys will be shown.
+    -- @treturn awful.keygrabber The keybrabber used to detect when the key is
+    --  released.
     -- @method show_help
     function widget_instance:show_help(c, s, show_args)
         show_args = show_args or {}
@@ -734,6 +795,7 @@ function widget.new(args)
     --- Add hotkey descriptions for third-party applications.
     -- @tparam table hotkeys Table with bindings,
     -- see `awful.hotkeys_popup.key.vim` as an example.
+    -- @noreturn
     -- @method add_hotkeys
     function widget_instance:add_hotkeys(hotkeys)
         for group, bindings in pairs(hotkeys) do
@@ -754,9 +816,10 @@ function widget.new(args)
     end
 
     --- Add hotkey group rules for third-party applications.
-    -- @tparam string group hotkeys group name,
-    -- @tparam table data rule data for the group
+    -- @tparam string group Hotkeys group name,
+    -- @tparam table data Rule data for the group
     -- see `awful.hotkeys_popup.key.vim` as an example.
+    -- @noreturn
     -- @method add_group_rules
     function widget_instance:add_group_rules(group, data)
         self.group_rules[group] = data
@@ -778,6 +841,8 @@ end
 -- @tparam[opt] table args Additional arguments.
 -- @tparam[opt=true] boolean args.show_awesome_keys Show AwesomeWM hotkeys.
 -- When set to `false` only app-specific hotkeys will be shown.
+-- @treturn awful.keygrabber The keybrabber used to detect when the key is
+--  released.
 -- @staticfct awful.hotkeys_popup.widget.show_help
 function widget.show_help(...)
     return get_default_widget():show_help(...)
@@ -787,19 +852,21 @@ end
 -- (default widget instance will be used).
 -- @tparam table hotkeys Table with bindings,
 -- see `awful.hotkeys_popup.key.vim` as an example.
+-- @noreturn
 -- @staticfct awful.hotkeys_popup.widget.add_hotkeys
 function widget.add_hotkeys(...)
-    return get_default_widget():add_hotkeys(...)
+    get_default_widget():add_hotkeys(...)
 end
 
 --- Add hotkey group rules for third-party applications
 -- (default widget instance will be used).
--- @tparam string group rule group name,
--- @tparam table data rule data for the group
+-- @tparam string group Rule group name,
+-- @tparam table data Rule data for the group
 -- see `awful.hotkeys_popup.key.vim` as an example.
+-- @noreturn
 -- @staticfct awful.hotkeys_popup.widget.add_group_rules
 function widget.add_group_rules(group, data)
-    return get_default_widget():add_group_rules(group, data)
+    get_default_widget():add_group_rules(group, data)
 end
 
 return widget

lib/awful/key.lua

@@ -43,7 +43,8 @@ local gobject = require("gears.object")
 -- keycode such as `#65`.
 --
 -- @property key
--- @param string
+-- @tparam string key
+-- @propertydefault Set in the constructor.
 
 --- The table of modifier keys.
 --
@@ -68,38 +69,43 @@ local gobject = require("gears.object")
 -- Please note that Awesome ignores the status of "Lock" and "Mod2" (Num Lock).
 --
 -- @property modifiers
--- @tparam table modifiers
+-- @tparam[opt={}] table modifiers
+-- @tablerowtype A list of modifier names in no specific order.
 
 --- The description of the function run from a key binding.
 --
 -- This is used, for example, by `awful.hotkeys_popup`.
 --
 -- @property description
--- @param string
+-- @tparam[opt=""] string description
 
 --- The key name.
 --
 -- This can be useful when searching for keybindings by keywords.
 --
 -- @property name
--- @param string
+-- @tparam[opt=""] string name
 
 --- The key group bound to a function in a key binding.
 --
 -- This is used, for example, by `awful.hotkeys_popup`.
 --
 -- @property group
--- @param string
+-- @tparam[opt=""] string group
 
 --- The callback when this key is pressed.
 --
 -- @property on_press
--- @param function
+-- @tparam[opt=nil] function|nil on_press
+-- @functionnoparam
+-- @functionnoreturn
 
 --- The callback when this key is released.
 --
 -- @property on_release
--- @param function
+-- @tparam[opt=nil] function|nil on_release
+-- @functionnoparam
+-- @functionnoreturn
 
 local key = { mt = {}, hotkeys = {} }
 
@@ -159,7 +165,8 @@ end
 
 --- Execute this keybinding.
 --
--- @method :trigger
+-- @method trigger
+-- @noreturn
 
 function key:trigger()
     local data = reverse_map[self]
@@ -432,10 +439,10 @@ function key.new(args, keycode, press, release, data)
 end
 
 --- Compare a key object with modifiers and key.
--- @param _key The key object.
--- @param pressed_mod The modifiers to compare with.
--- @param pressed_key The key to compare with.
--- @staticfct awful.key.match
+-- @tparam table pressed_mod The modifiers to compare with.
+-- @tparam string pressed_key The key to compare with.
+-- @treturn boolean If the key and modifier match.
+-- @method match
 function key.match(self, pressed_mod, pressed_key)
     -- First, compare key.
     if pressed_key ~= self.key then return false end

lib/awful/keyboard.lua

@@ -46,6 +46,7 @@ capi.awesome.connect_signal("xkb::map_changed", function() conversion = nil end)
 -- @tparam table modifiers A modified table. Valid modifiers are: `Any`, `Mod1`,
 --   `Mod2`, `Mod3`, `Mod4`, `Mod5`, `Shift`, `Lock` and `Control`.
 -- @tparam string key The key.
+-- @noreturn
 -- @staticfct awful.keyboard.emulate_key_combination
 function module.emulate_key_combination(modifiers, key)
     local modmap = generate_conversion_map()
@@ -90,6 +91,7 @@ end
 --
 -- @staticfct awful.keyboard.append_global_keybinding
 -- @tparam awful.key key The key object.
+-- @noreturn
 -- @see awful.key
 -- @see awful.keyboard.append_global_keybindings
 -- @see awful.keyboard.remove_global_keybinding
@@ -107,6 +109,7 @@ end
 -- @tparam table keys A table of `awful.key` objects. Optionally, it can have
 --  a `group` entry. If set, the `group` property will be set on all `awful.keys`
 --  objects.
+-- @noreturn
 -- @see awful.key
 -- @see awful.keyboard.append_global_keybinding
 -- @see awful.keyboard.remove_global_keybinding
@@ -131,6 +134,7 @@ end
 --
 -- @staticfct awful.keyboard.remove_global_keybinding
 -- @tparam awful.key key The key object.
+-- @noreturn
 -- @see awful.key
 -- @see awful.keyboard.append_global_keybinding
 
@@ -145,6 +149,7 @@ local default_keys = {}
 --
 -- @staticfct awful.keyboard.append_client_keybinding
 -- @tparam awful.key key The key.
+-- @noreturn
 -- @emits client_keybinding::added
 -- @emitstparam client_keybinding::added awful.key key The key.
 -- @see awful.key
@@ -164,6 +169,7 @@ end
 --
 -- @staticfct awful.keyboard.append_client_keybindings
 -- @tparam table keys A table containing `awful.key` objects.
+-- @noreturn
 -- @emits client_keybinding::added
 -- @emitstparam client_keybinding::added awful.key key The key.
 -- @see awful.key

lib/awful/keygrabber.lua

@@ -296,7 +296,10 @@ end
 -- @DOC_text_awful_keygrabber_timeout_EXAMPLE@
 --
 -- @property timeout
--- @param number
+-- @tparam[opt=nil] number|nil timeout
+-- @propertyunit second
+-- @negativeallowed false
+-- @propertytype nil No timeout.
 -- @see gears.timer
 -- @see timeout_callback
 
@@ -313,26 +316,23 @@ end
 --
 -- It can also be a table containing many keys (as values).
 --
--- @DOC_text_awful_keygrabber_stop_keys_EXAMPLE@
---
--- @DOC_text_awful_keygrabber_stop_key_EXAMPLE@
---
 -- Please note that modkeys are not accepted as `stop_key`s. You have to use
 -- their corresponding key names such as `Control_L`.
 --
 -- @property stop_key
--- @param[opt=nil] string|table stop_key
+-- @tparam[opt=nil] string|table|nil stop_key
+-- @propertyunit nil No stop key.
+-- @propertyunit string A single stop key.
+-- @propertyunit table One or more stop key(s).
+-- @tablerowtype A list of key names, such as `"Control"` or `"a"`.
 -- @see stop_event
 
 --- The event on which the keygrabbing will be terminated.
 --
--- the valid values are:
---
--- * "press" (default)
--- * "release"
---
 -- @property stop_event
--- @param string
+-- @tparam[opt="press"] string stop_event
+-- @propertyvalue "press" When the keyboard key is first pressed.
+-- @propertyvalue "release" When the keyboard key is released.
 -- @see stop_key
 
 --- Whether or not to execute the key press/release callbacks when keybindings are called.
@@ -344,14 +344,14 @@ end
 -- By default, keybindings block those callbacks from being executed.
 --
 -- @property mask_event_callback
--- @param[opt=true] boolean
+-- @tparam[opt=true] boolean mask_event_callback
 -- @see keybindings
 -- @see keyreleased_callback
 -- @see keypressed_callback
 
 --- Do not call the callbacks on modifier keys (like `Control` or `Mod4`) events.
 -- @property mask_modkeys
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean mask_modkeys
 -- @see mask_event_callback
 
 --- Export all keygrabber keybindings as root (global) keybindings.
@@ -365,7 +365,7 @@ end
 -- have a single instance.
 --
 -- @property export_keybindings
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean export_keybindings
 
 --- The root (global) keybinding to start this keygrabber.
 --
@@ -376,7 +376,8 @@ end
 -- @DOC_text_awful_keygrabber_root_keybindings_EXAMPLE@
 --
 -- @property root_keybindings
--- @param table
+-- @tparam[opt={}] table root_keybindings
+-- @tablerowtype A list of `awful.key` objects.
 -- @see export_keybindings
 -- @see keybindings
 
@@ -385,7 +386,8 @@ end
 -- This property contains a table of `awful.key` objects.
 --
 -- @property keybindings
--- @param table
+-- @tparam[opt={}] table keybindings
+-- @tablerowtype A list of `awful.key` objects.
 -- @see export_keybindings
 -- @see root_keybindings
 -- @see awful.key
@@ -402,7 +404,10 @@ end
 -- @DOC_text_awful_keygrabber_allowed_keys_EXAMPLE@
 --
 -- @property allowed_keys
--- @tparam[opt=nil] table|nil allowed_keys The list of keys.
+-- @tparam[opt=nil] table|nil allowed_keys
+-- @propertytype nil All keys are allowed.
+-- @propertytype table Only some keys are allowed.
+-- @tablerowtype A list of key names, such as `"Control"` or `"a"`.
 
 --- The sequence of keys recorded since the start of the keygrabber.
 --
@@ -415,7 +420,7 @@ end
 -- @DOC_text_awful_keygrabber_autostart_EXAMPLE@
 --
 -- @property sequence
--- @param string
+-- @tparam[opt=""] string sequence
 --
 
 --- The current (running) instance of this keygrabber.
@@ -500,6 +505,7 @@ end
 -- @method stop
 -- @tparam string|nil stop_key Override the key passed to `stop_callback` **DEPRECATED**
 -- @tparam tale|nil Override the modifiers passed to `stop_callback` **DEPRECATED**
+-- @noreturn
 -- @emits stopped
 -- @emits property::current_instance
 function keygrabber:stop(stop_key, stop_mods)
@@ -535,6 +541,7 @@ end
 -- @method add_keybinding
 -- @tparam awful.key key The key.
 -- @tparam string description.group The keybinding group
+-- @noreturn
 
 function keygrabber:add_keybinding(key, keycode, callback, description)
     local mods = not key._is_awful_key and key or nil
@@ -652,7 +659,7 @@ end
 --
 -- @callback keypressed_callback
 -- @tparam table self The current transaction object.
--- @tparam table mod The current modifiers (like "Control" or "Shift").
+-- @tparam table mod The current modifiers (like `"Control"` or `"Shift"`).
 -- @tparam string key The key name.
 -- @tparam string event The event ("press" or "release").
 -- @usage local function my_keypressed_cb(self, mod, key, command)
@@ -666,7 +673,7 @@ end
 -- end
 -- @callback keyreleased_callback
 -- @tparam table self The current transaction object.
--- @tparam table mod The current modifiers (like "Control" or "Shift").
+-- @tparam table mod The current modifiers (like `"Control"` or `"Shift"`).
 -- @tparam string key The key name.
 -- @tparam string event The event ("press" or "release")
 
@@ -698,7 +705,7 @@ end
 -- @tparam[opt=false] boolean args.export_keybindings Create root (global) keybindings.
 -- @tparam[opt=false] boolean args.autostart Start the grabbing immediately
 -- @tparam[opt=false] boolean args.mask_modkeys Do not call the callbacks on
---  modifier keys (like `Control` or `Mod4`) events.
+--  modifier keys (like `"Control"` or `"Mod4"`) events.
 -- @constructorfct awful.keygrabber
 function keygrab.run_with_keybindings(args)
     args = args or {}
@@ -852,6 +859,7 @@ local signals = {}
 -- @staticfct awful.keygrabber.connect_signal
 -- @tparam string name The signal name.
 -- @tparam function callback The callback.
+-- @noreturn
 function keygrab.connect_signal(name, callback)
     signals[name] = signals[name] or {}
 
@@ -865,6 +873,7 @@ end
 -- @staticfct awful.keygrabber.disconnect_signal
 -- @tparam string name The signal name.
 -- @tparam function callback The callback.
+-- @noreturn
 function keygrab.disconnect_signal(name, callback)
     signals[name] = signals[name] or {}
 
@@ -885,6 +894,7 @@ end
 -- @staticfct awful.keygrabber.emit_signal
 -- @tparam string name The signal name.
 -- @param ... Other arguments for the callbacks.
+-- @noreturn
 function keygrab.emit_signal(name, ...)
     signals[name] = signals[name] or {}
 

lib/awful/layout/init.lua

@@ -1,5 +1,29 @@
 ---------------------------------------------------------------------------
---- Layout module for awful.
+--- Deterministically lay the clients in a screen workarea.
+--
+-- The `awful.layout` module contains many sub-modules. Each of them contain
+-- one or more layout. `awful.layout` offers static layouts rather than
+-- tree based like other WMs. The layout have a small number of configuration
+-- variables:
+--
+-- * `master_width_factor`: The ratio between the main (master) section of the
+--  layout and a sub-section. For example, in the `tile.left` layout, the main
+--  (master) part contains `master_count` clients and the secondary part contains
+--  all other clients.
+-- * `master_count`: The number of clients which belong to the main (master) area.
+-- * `column_count`: The number of columns to store the clients in the secondary
+--   area.
+-- * `master_fill_policy`: When the number of clients is below `master_count`,
+--  how is the remaining space used.
+-- * `gaps`: The empty space between the clients.
+-- * `gap_single_client`: Same as gap, but when there is a single client. Gaps
+--  are often useful as a visual cue to know where a client starts and ends.
+--  This makes no sense when there is only one.
+--
+-- Not all layouts make use of all variables. Having such an overloaded meaning
+-- to a small set of variable is useful to attach those values to keybindings
+-- without having special logic for each layouts. AwesomeWM keybindings are not
+-- modal, so such "limitation" actually improves usability.
 --
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008 Julien Danjou
@@ -85,7 +109,7 @@ local arrange_lock = false
 local delayed_arrange = {}
 
 --- Get the current layout.
--- @param screen The screen.
+-- @tparam screen screen The screen.
 -- @return The layout function.
 -- @staticfct awful.layout.get
 function layout.get(screen)
@@ -98,9 +122,10 @@ function layout.get(screen)
 end
 
 --- Change the layout of the current tag.
--- @param i Relative index.
--- @param s The screen.
--- @param[opt] layouts A table of layouts.
+-- @tparam integer i Relative index.
+-- @tparam screen s The screen.
+-- @tparam[opt=s.selected_tag.layouts] table layouts A table of layouts.
+-- @noreturn
 -- @staticfct awful.layout.inc
 function layout.inc(i, s, layouts)
     if type(i) == "table" then
@@ -147,6 +172,7 @@ end
 --- Set the layout function of the current tag.
 -- @tparam layout|function l Layout object or function.
 -- @tparam[opt=mouse.screen.selected_tag] tag t The tag to modify.
+-- @noreturn
 -- @staticfct awful.layout.set
 function layout.set(l, t)
     t = t or capi.mouse.screen.selected_tag
@@ -208,7 +234,8 @@ function layout.parameters(t, screen)
 end
 
 --- Arrange a screen using its current layout.
--- @param screen The screen to arrange.
+-- @tparam screen screen The screen to arrange.
+-- @noreturn
 -- @staticfct awful.layout.arrange
 function layout.arrange(screen)
     screen = get_screen(screen)
@@ -251,6 +278,7 @@ end
 --
 -- @staticfct awful.layout.append_default_layout
 -- @tparam layout to_add A valid tag layout.
+-- @noreturn
 -- @see awful.layout.layouts
 function layout.append_default_layout(to_add)
     rawset(default_layouts, #default_layouts+1, to_add)
@@ -287,6 +315,7 @@ end
 --
 -- @staticfct awful.layout.append_default_layouts
 -- @tparam table layouts A table of valid tag layout.
+-- @noreturn
 -- @see awful.layout.layouts
 function layout.append_default_layouts(layouts)
     for _, l in ipairs(layouts) do

lib/awful/layout/suit/corner.lua

@@ -171,6 +171,7 @@ end
 -- Display master client in a corner of the screen, and slaves in one
 -- column and one row around the master.
 -- @clientlayout awful.layout.suit.corner.nw
+-- @usebeautiful beautiful.layout_cornernw
 corner.nw = {
         name = "cornernw",
         arrange = function (p) return do_corner(p, "NW") end,
@@ -181,6 +182,7 @@ corner.nw = {
 -- Display master client in a corner of the screen, and slaves in one
 -- column and one row around the master.
 -- @clientlayout awful.layout.suit.corner.ne
+-- @usebeautiful beautiful.layout_cornerne
 corner.ne = {
         name = "cornerne",
         arrange = function (p) return do_corner(p, "NE") end,
@@ -191,6 +193,7 @@ corner.ne = {
 -- Display master client in a corner of the screen, and slaves in one
 -- column and one row around the master.
 -- @clientlayout awful.layout.suit.corner.sw
+-- @usebeautiful beautiful.layout_cornersw
 corner.sw = {
         name = "cornersw",
         arrange = function (p) return do_corner(p, "SW") end,
@@ -201,6 +204,7 @@ corner.sw = {
 -- Display master client in a corner of the screen, and slaves in one
 -- column and one row around the master.
 -- @clientlayout awful.layout.suit.corner.se
+-- @usebeautiful beautiful.layout_cornerse
 corner.se = {
         name = "cornerse",
         arrange = function (p) return do_corner(p, "SE") end,

lib/awful/layout/suit/fair.lua

@@ -107,10 +107,12 @@ end
 --- The fair layout.
 -- Try to give all clients the same size.
 -- @clientlayout awful.layout.suit.fair
+-- @usebeautiful beautiful.layout_fairv
 
 --- The horizontal fair layout.
 -- Try to give all clients the same size.
 -- @clientlayout awful.layout.suit.fair.horizontal
+-- @usebeautiful beautiful.layout_fairh
 
 return fair
 

lib/awful/layout/suit/floating.lua

@@ -114,6 +114,7 @@ end
 
 --- The floating layout.
 -- @clientlayout awful.layout.suit.floating
+-- @usebeautiful beautiful.layout_floating
 
 floating.name = "floating"
 

lib/awful/layout/suit/magnifier.lua

@@ -143,6 +143,7 @@ end
 
 --- The magnifier layout.
 -- @clientlayout awful.layout.suit.magnifier
+-- @usebeautiful beautiful.layout_magnifier
 
 magnifier.name = "magnifier"
 

lib/awful/layout/suit/max.lua

@@ -43,6 +43,7 @@ end
 
 --- Maximized layout.
 -- @clientlayout awful.layout.suit.max
+-- @usebeautiful beautiful.layout_max
 max.name = "max"
 function max.arrange(p)
     return fmax(p, false)
@@ -53,6 +54,7 @@ end
 
 --- Fullscreen layout.
 -- @clientlayout awful.layout.suit.max.fullscreen
+-- @usebeautiful beautiful.layout_fullscreen
 max.fullscreen = {}
 max.fullscreen.name = "fullscreen"
 max.fullscreen.skip_gap = max.skip_gap

lib/awful/layout/suit/spiral.lua

@@ -71,6 +71,7 @@ end
 
 --- Dwindle layout.
 -- @clientlayout awful.layout.suit.spiral.dwindle
+-- @usebeautiful beautiful.layout_dwindle
 spiral.dwindle = {}
 spiral.dwindle.name = "dwindle"
 function spiral.dwindle.arrange(p)
@@ -79,6 +80,7 @@ end
 
 --- Spiral layout.
 -- @clientlayout awful.layout.suit.spiral.name
+-- @usebeautiful beautiful.layout_spiral
 spiral.name = "spiral"
 function spiral.arrange(p)
     return do_spiral(p, true)

lib/awful/layout/suit/tile.lua

@@ -312,6 +312,7 @@ end
 --- The main tile algo, on the right.
 -- @param screen The screen number to tile.
 -- @clientlayout awful.layout.suit.tile.right
+-- @usebeautiful beautiful.layout_tile
 tile.right = {}
 tile.right.name = "tile"
 tile.right.arrange = do_tile
@@ -323,6 +324,7 @@ end
 --- The main tile algo, on the left.
 -- @param screen The screen number to tile.
 -- @clientlayout awful.layout.suit.tile.left
+-- @usebeautiful beautiful.layout_tileleft
 tile.left = {}
 tile.left.name = "tileleft"
 tile.left.skip_gap = tile.skip_gap
@@ -336,6 +338,7 @@ end
 --- The main tile algo, on the bottom.
 -- @param screen The screen number to tile.
 -- @clientlayout awful.layout.suit.tile.bottom
+-- @usebeautiful beautiful.layout_tilebottom
 tile.bottom = {}
 tile.bottom.name = "tilebottom"
 tile.bottom.skip_gap = tile.skip_gap
@@ -349,6 +352,7 @@ end
 --- The main tile algo, on the top.
 -- @param screen The screen number to tile.
 -- @clientlayout awful.layout.suit.tile.top
+-- @usebeautiful beautiful.layout_tiletop
 tile.top = {}
 tile.top.name = "tiletop"
 tile.top.skip_gap = tile.skip_gap

lib/awful/menu.lua

@@ -1,5 +1,5 @@
 --------------------------------------------------------------------------------
---- A menu for awful.
+--- Create context menus, optionally with sub-menus.
 --
 -- @author Damien Leone <damien.leone@gmail.com>
 -- @author Julien Danjou <julien@danjou.info>
@@ -93,7 +93,7 @@ end
 -- @param color
 -- @see gears.color
 
---- The default sub-menu indicator if no menu_submenu_icon is provided.
+--- The default sub-menu indicator if no `menu_submenu_icon` is provided.
 -- @beautiful beautiful.menu_submenu
 -- @tparam[opt="▶"] string menu_submenu The sub-menu text.
 -- @see beautiful.menu_submenu_icon
@@ -357,8 +357,10 @@ end
 
 
 --- Show a menu.
--- @param args The arguments
--- @param args.coords Menu position defaulting to mouse.coords()
+-- @tparam[opt={}] table args The arguments
+-- @tparam[opt=mouse.coords] table args.coords The menu position. A table with
+--  `x` and `y` as keys and position (in pixels) as values.
+-- @noreturn
 -- @method show
 function menu:show(args)
     args = args or {}
@@ -374,6 +376,7 @@ end
 
 --- Hide a menu popup.
 -- @method hide
+-- @noreturn
 function menu:hide()
     -- Remove items from screen
     for i = 1, #self.items do
@@ -390,8 +393,10 @@ function menu:hide()
 end
 
 --- Toggle menu visibility.
--- @param args The arguments
--- @param args.coords Menu position {x,y}
+-- @tparam table args The arguments.
+-- @tparam[opt=mouse.coords] table args.coords The menu position. A table with
+--  `x` and `y` as keys and position (in pixels) as values.
+-- @noreturn
 -- @method toggle
 function menu:toggle(args)
     if self.wibox.visible then
@@ -403,6 +408,7 @@ end
 
 --- Update menu content.
 -- @method update
+-- @noreturn
 function menu:update()
     if self.wibox.visible then
         self:show({ coords = { x = self.x, y = self.y } })
@@ -413,16 +419,18 @@ end
 --- Get the elder parent so for example when you kill
 -- it, it will destroy the whole family.
 -- @method get_root
+-- @treturn awful.menu The root menu.
 function menu:get_root()
     return self.parent and menu.get_root(self.parent) or self
 end
 
 --- Add a new menu entry.
 -- args.* params needed for the menu entry constructor.
--- @param args The item params
--- @param args.new (Default: awful.menu.entry) The menu entry constructor.
--- @param[opt] args.theme The menu entry theme.
--- @param[opt] index The index where the new entry will inserted.
+-- @tparam table args The item params.
+-- @tparam[opt=awful.menu.entry] function args.new The menu entry constructor.
+-- @tparam[opt] table args.theme The menu entry theme.
+-- @tparam[opt] number index The index where the new entry will inserted.
+-- @treturn table|nil The new item.
 -- @method add
 function menu:add(args, index)
     if not args then return end
@@ -479,7 +487,8 @@ function menu:add(args, index)
 end
 
 --- Delete menu entry at given position.
--- @param num The position in the table of the menu entry to be deleted; can be also the menu entry itself.
+-- @tparam table|number num The index in the table of the menu entry to be deleted; can be also the menu entry itself.
+-- @noreturn
 -- @method delete
 function menu:delete(num)
     if type(num) == "table" then
@@ -580,8 +589,8 @@ end
 
 --- Default awful.menu.entry constructor.
 -- @param parent The parent menu (TODO: This is apparently unused)
--- @param args the item params
--- @return table with 'widget', 'cmd', 'akey' and all the properties the user wants to change
+-- @param args The item params
+-- @return table With 'widget', 'cmd', 'akey' and all the properties the user wants to change
 -- @constructorfct awful.menu.entry
 function menu.entry(parent, args) -- luacheck: no unused args
     args = args or {}
@@ -673,14 +682,24 @@ end
 --------------------------------------------------------------------------------
 
 --- Create a menu popup.
--- @param args Table containing the menu information.
---
--- * Key items: Table containing the displayed items. Each element is a table by default (when element 'new' is
---   awful.menu.entry) containing: item name, triggered action (submenu table or function), item icon (optional).
--- * Keys theme.[fg|bg]_[focus|normal], theme.border_color, theme.border_width, theme.submenu_icon, theme.height
---   and theme.width override the default display for your menu and/or of your menu entry, each of them are optional.
--- * Key auto_expand controls the submenu auto expand behaviour by setting it to true (default) or false.
 --
+-- @tparam table args Table containing the menu information.
+-- @tparam[opt=true] boolean args.auto_expand Controls the submenu auto expand behaviour.
+-- @tparam table args.items Table containing the displayed items. Each element is a
+--   table by default (when element 'new' is awful.menu.entry) containing: item
+--   name, triggered action (submenu table or function), item icon (optional).
+-- @tparam table args.theme
+-- @tparam[opt=beautiful.menu_fg_normal] color args.theme.fg_normal
+-- @tparam[opt=beautiful.menu_bg_normal] color args.theme.bg_normal
+-- @tparam[opt=beautiful.menu_fg_focus] color args.theme.fg_focus
+-- @tparam[opt=beautiful.menu_bg_focus] color args.theme.bg_focus
+-- @tparam[opt=beautiful.menu_border_color] color args.theme.border
+-- @tparam[opt=beautiful.menu_border_width] integer args.theme.border_width
+-- @tparam[opt=beautiful.menu_height] integer args.theme.height
+-- @tparam[opt=beautiful.menu_width] integer args.theme.width
+-- @tparam[opt=beautiful.menu_font] string args.theme.font
+-- @tparam[opt=beautiful.menu_submenu_icon] gears.surface|string args.theme.submenu_icon
+-- @tparam[opt=beautiful.menu_submenu] string args.theme.submenu
 -- @param parent Specify the parent menu if we want to open a submenu, this value should never be set by the user.
 -- @constructorfct awful.menu
 -- @usage -- The following function builds and shows a menu of clients that match

lib/awful/mouse/client.lua

@@ -13,9 +13,9 @@ local module = {}
 
 --- Move a client.
 -- @staticfct awful.mouse.client.move
--- @param c The client to move, or the focused one if nil.
+-- @tparam client c The client to move, or the focused one if nil.
 -- @param snap The pixel to snap clients.
--- @param finished_cb Deprecated, do not use.
+-- @noreturn
 -- @request client geometry mouse.move granted When `awful.mouse.client.move` is
 --  called.
 function module.move(c, snap, finished_cb) --luacheck: no unused args
@@ -69,8 +69,8 @@ end
 --- Get a client corner coordinates.
 -- @deprecated awful.mouse.client.corner
 -- @tparam[opt=client.focus] client c The client to get corner from, focused one by default.
--- @tparam string corner The corner to use: auto, top_left, top_right, bottom_left,
--- bottom_right, left, right, top bottom. Default is auto, and auto find the
+-- @tparam string corner The corner to use: `auto`, `top_left`, `top_right`, `bottom_left`,
+-- `bottom_right`, `left`, `right`, `top` or `bottom`. Default is `auto`. `auto` finds the
 -- nearest corner.
 -- @treturn string The corner name
 -- @treturn number x The horizontal position

lib/awful/mouse/init.lua

@@ -35,12 +35,12 @@ mouse.wibox = {}
 --
 -- @DOC_screen_client_snap_EXAMPLE@
 --
--- @tfield integer snap.default_distance
+-- @tfield integer awful.mouse.snap.default_distance
 -- @tparam[opt=8] integer default_distance
 -- @see awful.mouse.snap
 
 --- The default distance before activating screen edge snap.
--- @tfield integer snap.aerosnap_distance
+-- @tfield integer awful.mouse.snap.aerosnap_distance
 -- @tparam[opt=16] integer aerosnap_distance
 -- @see awful.mouse.snap
 
@@ -48,15 +48,15 @@ mouse.wibox = {}
 --
 --@DOC_awful_placement_aero_snap_EXAMPLE@
 --
--- @tfield[opt=true] boolean snap.edge_enabled
+-- @tfield[opt=true] boolean awful.mouse.snap.edge_enabled
 -- @tparam boolean edge_enabled
 
 --- Enable client to client snapping.
--- @tfield[opt=true] boolean snap.client_enabled
+-- @tfield[opt=true] boolean awful.mouse.snap.client_enabled
 -- @tparam boolean client_enabled
 
 --- Enable changing tag when a client is dragged to the edge of the screen.
--- @tfield[opt=false] boolean drag_to_tag.enabled
+-- @tfield[opt=false] boolean awful.mouse.drag_to_tag.enabled
 -- @tparam boolean enabled
 
 --- The snap outline background color.
@@ -65,7 +65,7 @@ mouse.wibox = {}
 
 --- The snap outline width.
 -- @beautiful beautiful.snap_border_width
--- @param integer
+-- @tparam integer snap_border_width
 
 --- The snap outline shape.
 -- @beautiful beautiful.snap_shape
@@ -75,9 +75,17 @@ mouse.wibox = {}
 -- @beautiful beautiful.snapper_gap
 -- @tparam[opt=0] number snapper_gap
 
+--- The resize cursor name.
+-- @beautiful beautiful.cursor_mouse_resize
+-- @tparam[opt="cross"] string cursor
+
+--- The move cursor name.
+-- @beautiful beautiful.cursor_mouse_move
+-- @tparam[opt="fleur"] string cursor
+
 --- Get the client object under the pointer.
 -- @deprecated awful.mouse.client_under_pointer
--- @return The client object under the pointer, if one can be found.
+-- @treturn client|nil The client object under the pointer, if one can be found.
 -- @see current_client
 function mouse.client_under_pointer()
     gdebug.deprecate("Use mouse.current_client instead of awful.mouse.client_under_pointer()", {deprecated_in=4})
@@ -108,7 +116,8 @@ end, "mouse.resize")
 
 --- Get the client currently under the mouse cursor.
 -- @property current_client
--- @tparam client|nil The client
+-- @tparam[opt=nil] client|nil current_client
+-- @propertytype nil When the mouse cursor is not over a client.
 
 function mouse.object.get_current_client()
     local obj = capi.mouse.object_under_pointer()
@@ -119,7 +128,8 @@ end
 
 --- Get the wibox currently under the mouse cursor.
 -- @property current_wibox
--- @tparam wibox|nil The wibox
+-- @tparam[opt=nil] wibox|nil current_wibox
+-- @propertytype nil When the mouse cursor is not over a wibox.
 
 function mouse.object.get_current_wibox()
     local obj = capi.mouse.object_under_pointer()
@@ -131,10 +141,10 @@ end
 --- Get the widgets currently under the mouse cursor.
 --
 -- @property current_widgets
--- @tparam nil|table list The widget list
--- @treturn table The list of widgets.The first element is the biggest
--- container while the last is the topmost widget. The table contains *x*, *y*,
--- *width*, *height* and *widget*.
+-- @tparam[opt=nil] nil|table current_widgets
+-- @tablerowtype table The list of `wibox.widget`s. The first element is the biggest
+-- container while the last is the topmost widget.
+-- @propertytype nil When the mouse cursor is not over any widget.
 
 function mouse.object.get_current_widgets()
     local w = mouse.object.get_current_wibox()
@@ -156,8 +166,8 @@ end
 
 --- Get the topmost widget currently under the mouse cursor.
 -- @property current_widget
--- @tparam widget|nil widget The widget
--- @treturn ?widget The widget
+-- @tparam[opt=nil] widget|nil current_widget
+-- @propertytype nil When the mouse cursor is not over a widget.
 -- @see current_widget_geometry
 
 function mouse.object.get_current_widget()
@@ -170,7 +180,13 @@ end
 
 --- Get the current widget geometry.
 -- @property current_widget_geometry
--- @tparam ?table The geometry.
+-- @tparam[opt=nil] table|nil current_widget_geometry
+-- @tparam number current_widget_geometry.x
+-- @tparam number current_widget_geometry.y
+-- @tparam number current_widget_geometry.width
+-- @tparam number current_widget_geometry.height
+-- @propertytype nil When there is no current widgets.
+-- @propertytype table
 -- @see current_widget
 
 function mouse.object.get_current_widget_geometry()
@@ -181,7 +197,13 @@ end
 
 --- Get the current widget geometries.
 -- @property current_widget_geometries
--- @tparam ?table A list of geometry tables.
+-- @tparam[opt=nil] table|nil current_widget_geometries A list of geometry tables.
+-- @propertytype nil When there is no widgets.
+-- @propertytype table A list of geometry tables.
+-- @tablerowkey x integer
+-- @tablerowkey y integer
+-- @tablerowkey width integer
+-- @tablerowkey height integer
 -- @see current_widgets
 
 function mouse.object.get_current_widget_geometries()
@@ -193,6 +215,7 @@ end
 --- Move the wibox under the cursor.
 -- @staticfct awful.mouse.wibox.move
 -- @tparam wibox w The wibox to move, or none to use that under the pointer
+-- @noreturn
 -- @request wibox geometry mouse.move granted Requests to move the wibox.
 function mouse.wibox.move(w)
     w = w or mouse.current_wibox
@@ -222,15 +245,15 @@ end
 
 --- True if the left mouse button is pressed.
 -- @property is_left_mouse_button_pressed
--- @param boolean
+-- @tparam[opt=false] boolean is_left_mouse_button_pressed
 
 --- True if the right mouse button is pressed.
 -- @property is_right_mouse_button_pressed
--- @param boolean
+-- @tparam[opt=false] boolean is_right_mouse_button_pressed
 
 --- True if the middle mouse button is pressed.
 -- @property is_middle_mouse_button_pressed
--- @param boolean
+-- @tparam[opt=false] boolean is_middle_mouse_button_pressed
 
 --- Add an `awful.button` based mousebinding to the global set.
 --
@@ -240,6 +263,7 @@ end
 --
 -- @staticfct awful.mouse.append_global_mousebinding
 -- @tparam awful.button button The button object.
+-- @noreturn
 -- @see awful.button
 
 function mouse.append_global_mousebinding(button)
@@ -252,9 +276,11 @@ end
 -- no focused client. If your intent is too add a mousebinding which acts on
 -- the focused client do **not** use this
 --
+-- @staticfct awful.mouse.append_global_mousebindings
 -- @tparam table buttons A table of `awful.button` objects. Optionally, it can have
 --  a `group` entry. If set, the `group` property will be set on all `awful.buttons`
 --  objects.
+-- @noreturn
 -- @see awful.button
 
 function mouse.append_global_mousebindings(buttons)
@@ -277,6 +303,7 @@ end
 --
 -- @staticfct awful.mouse.remove_global_mousebinding
 -- @tparam awful.button button The button object.
+-- @noreturn
 -- @see awful.button
 
 function mouse.remove_global_mousebinding(button)
@@ -289,6 +316,7 @@ local default_buttons = {}
 --
 -- @staticfct awful.mouse.append_client_mousebinding
 -- @tparam awful.button button The button.
+-- @noreturn
 -- @emits client_mousebinding::added
 -- @emitstparam client_mousebinding::added awful.button button The button.
 -- @see awful.button
@@ -308,6 +336,7 @@ end
 --
 -- @staticfct awful.mouse.append_client_mousebindings
 -- @tparam table buttons A table containing `awful.button` objects.
+-- @noreturn
 -- @see awful.button
 -- @see awful.keyboard.append_client_keybinding
 -- @see awful.mouse.append_client_mousebinding
@@ -387,11 +416,13 @@ end)
 -- @tparam[opt=nil] integer coords_table.y The mouse vertical position
 -- @tparam[opt=false] boolean silent Disable mouse::enter or mouse::leave events that
 --  could be triggered by the pointer when moving.
--- @treturn integer table.x The horizontal position
--- @treturn integer table.y The vertical position
--- @treturn table table.buttons Table containing the status of buttons, e.g. field [1] is true
---  when button 1 is pressed.
+-- @treturn table The coords. It contains the `x`, `y` and `buttons` keys.
+--  `buttons` contains the button number as key and a boolean as value (if it is
+--  pressed).
 -- @staticfct mouse.coords
+-- @see is_left_mouse_button_pressed
+-- @see is_right_mouse_button_pressed
+-- @see is_middle_mouse_button_pressed
 
 capi.client.connect_signal("scanning", function()
     capi.client.emit_signal("request::default_mousebindings", "startup")

lib/awful/mouse/resize.lua

@@ -33,14 +33,6 @@ local cursors = {
     ["mouse.resize_bottom_right"] = "bottom_right_corner",
 }
 
---- The resize cursor name.
--- @beautiful beautiful.cursor_mouse_resize
--- @tparam[opt=cross] string cursor
-
---- The move cursor name.
--- @beautiful beautiful.cursor_mouse_move
--- @tparam[opt=fleur] string cursor
-
 --- Set the resize mode.
 -- The available modes are:
 --
@@ -60,7 +52,7 @@ end
 -- This callback will be executed before the mouse grabbing starts.
 -- @function awful.mouse.resize.add_enter_callback
 -- @tparam function cb The callback (or nil)
--- @tparam[default=other] string context The callback context
+-- @tparam[opt="other"] string context The callback context
 function module.add_enter_callback(cb, context)
     context = context or "other"
     callbacks.enter[context] = callbacks.enter[context] or {}
@@ -72,7 +64,7 @@ end
 -- applying the operation.
 -- @function awful.mouse.resize.add_move_callback
 -- @tparam function cb The callback (or nil)
--- @tparam[default=other] string context The callback context
+-- @tparam[opt="other"] string context The callback context
 function module.add_move_callback(cb, context)
     context = context or  "other"
     callbacks.move[context] = callbacks.move[context]  or {}
@@ -83,7 +75,7 @@ end
 -- This callback is executed just before the `mousegrabber` stop
 -- @function awful.mouse.resize.add_leave_callback
 -- @tparam function cb The callback (or nil)
--- @tparam[default=other] string context The callback context
+-- @tparam[opt="other"] string context The callback context
 function module.add_leave_callback(cb, context)
     context = context or  "other"
     callbacks.leave[context] = callbacks.leave[context]  or {}
@@ -101,9 +93,11 @@ end
 --
 -- @function awful.mouse.resize
 -- @tparam client client A client.
--- @tparam[default=mouse.resize] string context The resizing context.
+-- @tparam[opt=mouse.resize] string context The resizing context.
 -- @tparam[opt={}] table args A set of `awful.placement` arguments.
 -- @request wibox geometry mouse.resize granted Requests to resize the wibox.
+-- @usebeautiful beautiful.cursor_mouse_move
+-- @usebeautiful beautiful.cursor_mouse_resize
 local function handler(_, client, context, args) --luacheck: no unused_args
     args = args or {}
     context = context or "mouse.resize"

lib/awful/mouse/snap.lua

@@ -191,13 +191,19 @@ local function snap_inside(g, sg, snap)
 end
 
 --- Snap a client to the closest client or screen edge.
+--
 -- @function awful.mouse.snap
--- @param c The client to snap.
--- @param snap The pixel to snap clients.
--- @param x The client x coordinate.
--- @param y The client y coordinate.
--- @param fixed_x True if the client isn't allowed to move in the x direction.
--- @param fixed_y True if the client isn't allowed to move in the y direction.
+-- @tparam[opt=client.focus] client c The client to snap.
+-- @tparam integer snap The pixel to snap clients.
+-- @tparam integer x The client x coordinate.
+-- @tparam integer y The client y coordinate.
+-- @tparam boolean fixed_x True if the client isn't allowed to move in the x direction.
+-- @tparam boolean fixed_y True if the client isn't allowed to move in the y direction.
+-- @treturn table The new geometry.
+-- @usebeautiful beautiful.snap_bg
+-- @usebeautiful beautiful.snap_border_width
+-- @usebeautiful beautiful.snap_shape
+-- @usebeautiful beautiful.snapper_gap
 function module.snap(c, snap, x, y, fixed_x, fixed_y)
     snap = snap or module.default_distance
     c = c or capi.client.focus

lib/awful/permissions/init.lua

@@ -1,5 +1,19 @@
 ---------------------------------------------------------------------------
---- Implements EWMH requests handling.
+--- Default implementation of the various requests handers.
+--
+-- AwesomeWM has many `request::` signals across the core APIs. They help
+-- decouple the default behavior from the core API. The request handlers
+-- can be disconnected and replaced by module or `rc.lua` to alter
+-- AwesomeWM behavior.
+--
+-- This module provides the default implementation of those request handlers.
+-- Beside some legacy signals, most request handlers have a main object, a
+-- named context and a table containing any low-level hints the core code is
+-- aware of. Each default handler implement a context based filter mechanism.
+-- This filter is called the "permissions". It allows requests to be denied.
+-- For example, if a tiled client asks to be resized or moved, the permission
+-- and deny it. In the documentation, many objects and properties have a
+-- "permissions" section you can display by clicking "show more".
 --
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2009 Julien Danjou
@@ -38,18 +52,18 @@ local permissions = {
 -- @beautiful beautiful.maximized_hide_border
 -- @tparam[opt=false] boolean maximized_hide_border
 
---- The list of all registered generic request::activate (focus stealing)
+--- The list of all registered generic `request::activate` (focus stealing)
 -- filters. If a filter is added to only one context, it will be in
 -- `permissions.contextual_activate_filters`["context_name"].
--- @table[opt={}] generic_activate_filters
+-- @table[opt={}] awful.permissions.generic_activate_filters
 -- @see permissions.activate
 -- @see permissions.add_activate_filter
 -- @see permissions.remove_activate_filter
 
---- The list of all registered contextual request::activate (focus stealing)
+--- The list of all registered contextual `request::activate` (focus stealing)
 -- filters. If a filter is added to only one context, it will be in
 -- `permissions.generic_activate_filters`.
--- @table[opt={}] contextual_activate_filters
+-- @table[opt={}] awful.permissions.contextual_activate_filters
 -- @see permissions.activate
 -- @see permissions.add_activate_filter
 -- @see permissions.remove_activate_filter
@@ -143,12 +157,13 @@ end
 -- @tparam client c A client to use
 -- @tparam string context The context where this signal was used.
 -- @tparam[opt] table hints A table with additional hints:
--- @tparam[opt=false] boolean hints.raise should the client be unminimized
+-- @tparam[opt=false] boolean hints.raise Should the client be unminimized
 --  and raised?
--- @tparam[opt=false] boolean hints.switch_to_tag should the client's first tag
+-- @tparam[opt=false] boolean hints.switch_to_tag Should the client's first tag
 --  be selected if none of the client's tags are selected?
 -- @tparam[opt=false] boolean hints.switch_to_tags Select all tags associated
 --  with the client.
+-- @sourcesignal client request::activate
 function permissions.activate(c, context, hints) -- luacheck: no unused args
     if not pcommon.check(c, "client", "activate", context) then return end
 
@@ -226,6 +241,7 @@ end
 --
 -- @tparam function f The callback
 -- @tparam[opt] string context The `request::activate` context
+-- @noreturn
 -- @see generic_activate_filters
 -- @see contextual_activate_filters
 -- @see remove_activate_filter
@@ -288,8 +304,10 @@ end
 --
 -- @signalhandler awful.permissions.tag
 -- @tparam client c A client to tag
--- @tparam[opt] tag|boolean t A tag to use. If true, then the client is made sticky.
--- @tparam[opt={}] table hints Extra information
+-- @tparam[opt] tag|boolean t A tag to use. If `true`, then the client is made `sticky`.
+-- @tparam[opt={}] table hints Extra information.
+-- @tparam[opt=nil] nil|string hints.reason Why the tag is being changed.
+-- @sourcesignal client request::tag
 function permissions.tag(c, t, hints) --luacheck: no unused
     -- There is nothing to do
     if not t and #get_valid_tags(c, c.screen) > 0 then return end
@@ -316,6 +334,7 @@ end
 -- @signalhandler awful.permissions.urgent
 -- @tparam client c A client
 -- @tparam boolean urgent If the client should be urgent
+-- @sourcesignal client request::urgent
 function permissions.urgent(c, urgent)
     if c ~= client.focus and not aclient.property.get(c,"ignore_urgent") then
         c.urgent = urgent
@@ -338,6 +357,11 @@ local context_mapper = {
 -- @tparam client c The client
 -- @tparam string context The context
 -- @tparam[opt={}] table hints The hints to pass to the handler
+-- @tparam[opt=true] boolean hints.store_geometry Create a memento of the
+--  previous geometry in case it has to be restored.
+-- @tparam[opt=true] boolean hints.honor_workarea Avoid overlapping the `wibar`s
+--  or other desktop decoration when applying the geometry.
+-- @sourcesignal client request::geometry
 function permissions.geometry(c, context, hints)
     if not pcommon.check(c, "client", "geometry", context) then return end
 
@@ -407,6 +431,11 @@ end
 -- @tparam wibox w The wibox.
 -- @tparam string context The context
 -- @tparam[opt={}] table hints The hints to pass to the handler
+-- @tparam[opt] integer hints.x The horizontal position.
+-- @tparam[opt] integer hints.y The vertical position.
+-- @tparam[opt] integer hints.width The wibox width.
+-- @tparam[opt] integer hints.height The wibox height.
+-- @sourcesignal client request::geometry
 function permissions.wibox_geometry(w, context, hints)
     if not pcommon.check(w, "wibox", "geometry", context) then return end
 
@@ -416,14 +445,17 @@ end
 --- Merge the 2 requests sent by clients wanting to be maximized.
 --
 -- The X clients set 2 flags (atoms) when they want to be maximized. This caused
--- 2 request::geometry to be sent. This code gives some time for them to arrive
+-- 2 `request::geometry` to be sent. This code gives some time for them to arrive
 -- and send a new `request::geometry` (through the property change) with the
 -- combined state.
 --
 -- @signalhandler awful.permissions.merge_maximization
 -- @tparam client c The client
 -- @tparam string context The context
--- @tparam[opt={}] table hints The hints to pass to the handler
+-- @tparam[opt={}] table hints The hints to pass to the handler.
+-- @tparam[opt=false] boolean hints.toggle Toggle the maximization state rather
+--  than set it to `true`.
+-- @sourcesignal client request::geometry
 function permissions.merge_maximization(c, context, hints)
     if not pcommon.check(c, "client", "geometry", context) then return end
 
@@ -506,7 +538,12 @@ end
 -- @signalhandler awful.permissions.client_geometry_requests
 -- @tparam client c The client
 -- @tparam string context The context
--- @tparam[opt={}] table hints The hints to pass to the handler
+-- @tparam[opt={}] table hints The hints to pass to the handler.
+-- @tparam[opt] integer hints.x The horizontal position.
+-- @tparam[opt] integer hints.y The vertical position.
+-- @tparam[opt] integer hints.width The client width.
+-- @tparam[opt] integer hints.height The client height.
+-- @sourcesignal client request::geometry
 function permissions.client_geometry_requests(c, context, hints)
     if not pcommon.check(c, "client", "geometry", context) then return end
 
@@ -539,13 +576,16 @@ end, "mouse_enter")
 --
 -- To replace this handler with your own, use:
 --
---    client.disconnect_signal("request::border", awful.ewmh.update_border)
+--    client.disconnect_signal("request::border", awful.permisions.update_border)
 --
 -- The default implementation chooses from dozens beautiful theme variables
 -- depending if the client is tiled, floating, maximized and then from its state
 -- (urgent, new, active, normal)
 --
 -- @signalhandler awful.permissions.update_border
+-- @tparam client c The client.
+-- @tparam string context Why is the border changed.
+-- @sourcesignal client request::border
 -- @usebeautiful beautiful.border_color_marked
 -- @usebeautiful beautiful.border_color_active
 -- @usebeautiful beautiful.border_color_normal
@@ -604,6 +644,8 @@ end, "mouse_enter")
 -- @usebeautiful beautiful.opacity_normal
 -- @usebeautiful beautiful.opacity_new
 -- @usebeautiful beautiful.opacity_urgent
+-- @see client.border_width
+-- @see client.border_color
 
 function permissions.update_border(c, context)
     if not pcommon.check(c, "client", "border", context) then return end
@@ -729,6 +771,12 @@ local activate_context_map = {
 -- * history    : *autofocus.check_focus*
 --
 -- @signalhandler awful.permissions.autoactivate
+-- @tparam client c The client.
+-- @tparam string context Why is the client auto-activated.
+-- @tparam[opt={}] table hints Extra arguments.
+-- @sourcesignal client request::activated
+-- @see activate
+-- @see client:activate
 function permissions.autoactivate(c, context, args)
     if not pcommon.check(c, "client", "autoactivate", context) then return end
 

lib/awful/popup.lua

@@ -145,13 +145,6 @@ local popup = {}
 -- parent menu. If there is no space on the right, it tries on the left and so
 -- on.
 --
--- Valid directions are:
---
--- * left
--- * right
--- * top
--- * bottom
---
 -- The basic use case for this method is to give it a parent wibox:
 --
 -- @DOC_awful_popup_position1_EXAMPLE@
@@ -162,8 +155,16 @@ local popup = {}
 -- @DOC_awful_popup_position2_EXAMPLE@
 --
 -- @property preferred_positions
--- @tparam table|string preferred_positions A position name or an ordered
---  table of positions
+-- @tparam table|string preferred_positions
+-- @propertydefault `{ "right", "left", "top", "bottom" }`
+-- @propertytype string A single position with no fallback. It will be used
+--  even if it doesn't fit.
+-- @propertytype table A list of possible positions. The first one to fit will be
+--  used.
+-- @propertyvalue "left"
+-- @propertyvalue "right"
+-- @propertyvalue "top"
+-- @propertyvalue "bottom"
 -- @see awful.placement.next_to
 -- @see awful.popup.preferred_anchors
 -- @propemits true false
@@ -176,12 +177,6 @@ end
 
 --- Set the preferred popup anchors relative to the parent.
 --
--- The possible values are:
---
--- * front
--- * middle
--- * back
---
 -- For details information, see the `awful.placement.next_to` documentation.
 --
 -- In this example, it is possible to see the effect of having a fallback
@@ -190,8 +185,14 @@ end
 -- @DOC_awful_popup_anchors_EXAMPLE@
 --
 -- @property preferred_anchors
--- @tparam table|string preferred_anchors Either a single anchor name or a table
+-- @tparam[opt="back"] table|string preferred_anchors
 --  ordered by priority.
+-- @propertytype string A single anchor value with no fallback.
+-- @propertytype table A list of possible anchor, the first one has the higher
+--  priority, but will fallback if it doesn't fit.
+-- @propertyvalue "front"
+-- @propertyvalue "middle"
+-- @propertyvalue "back"
 -- @propemits true false
 -- @see awful.placement.next_to
 -- @see awful.popup.preferred_positions
@@ -210,7 +211,14 @@ end
 -- isn't enough space, it can also be one of the fallback.
 --
 -- @property current_position
--- @tparam string current_position Either "left", "right", "top" or "bottom"
+-- @tparam string current_position
+-- @propertydefault This depends on where the popup was displayed.
+-- @propertyvalue "left"
+-- @propertyvalue "right"
+-- @propertyvalue "top"
+-- @propertyvalue "bottom"
+-- @readonly
+-- @see awful.popup.preferred_positions
 
 function popup:get_current_position()
     return self._private.current_position
@@ -224,7 +232,13 @@ end
 -- opposite direction from the anchor.
 --
 -- @property current_anchor
--- @tparam string current_anchor Either "front", "middle", "back"
+-- @tparam string current_anchor
+-- @propertydefault This depends on where the popup was displayed.
+-- @propertyvalue "front"
+-- @propertyvalue "middle"
+-- @propertyvalue "back"
+-- @readonly
+-- @see awful.popup.preferred_anchors
 
 function popup:get_current_anchor()
     return self._private.current_anchor
@@ -264,6 +278,7 @@ end
 -- @tparam widget widget The widget
 -- @tparam[opt=1] number button The button index
 -- @method bind_to_widget
+-- @noreturn
 function popup:bind_to_widget(widget, button)
     if not self._private.button_for_widget then
         self._private.button_for_widget = {}
@@ -274,8 +289,10 @@ function popup:bind_to_widget(widget, button)
 end
 
 --- Unbind the popup from a widget button.
--- @tparam widget widget The widget
+-- @tparam widget widget
+-- @propertytype widget A widget or declarative widget construct.
 -- @method unbind_to_widget
+-- @noreturn
 function popup:unbind_to_widget(widget)
     widget:disconnect_signal("button::press", self._private.show_fct)
 end
@@ -296,25 +313,33 @@ end
 --- The popup minimum width.
 --
 -- @property minimum_width
--- @tparam[opt=1] number minimum_width The minimum width.
+-- @tparam[opt=1] integer minimum_width
+-- @propertyunit pixel
+-- @rangestart 1
 -- @propemits true false
 
 --- The popup minimum height.
 --
 -- @property minimum_height
--- @tparam[opt=1] number minimum_height The minimum height.
+-- @tparam[opt=1] integer minimum_height
+-- @propertyunit pixel
+-- @rangestart 1
 -- @propemits true false
 
 --- The popup maximum width.
 --
 -- @property maximum_width
--- @tparam[opt=1] number maximum_width The maximum width.
+-- @tparam[opt=1] integer maximum_width
+-- @propertyunit pixel
+-- @rangestart 1
 -- @propemits true false
 
 --- The popup maximum height.
 --
 -- @property maximum_height
--- @tparam[opt=1] number maximum_height The maximum height.
+-- @tparam[opt=1] integer maximum_height
+-- @propertyunit pixel
+-- @rangestart 1
 -- @propemits true false
 
 for _, orientation in ipairs {"_width", "_height"} do
@@ -338,9 +363,13 @@ end
 --
 -- @DOC_awful_popup_position3_EXAMPLE@
 -- @property offset
--- @tparam table|number offset An integer value or a `{x=, y=}` table.
--- @tparam[opt=offset] number offset.x The horizontal distance.
--- @tparam[opt=offset] number offset.y The vertical distance.
+-- @tparam[opt=0] table|integer offset
+-- @tparam[opt=0] integer offset.x The horizontal offset.
+-- @tparam[opt=0] integer offset.y The vertical offset.
+-- @propertytype integer A value for both `x` and `y` simultaneously.
+-- @propertytype table Specify values for `x` and `y` individually.
+-- @negativeallowed true
+-- @propertyunit pixel
 -- @propemits true false
 
 function popup:set_offset(offset)
@@ -367,10 +396,10 @@ end
 
 --- Set the placement function.
 --
--- @tparam[opt=next_to] function|string|boolean The placement function or name
--- (or false to disable placement)
 -- @property placement
--- @param function
+-- @tparam[opt=awful.placement.next_to] placement|string|boolean placement
+-- @propertytype boolean Use `false` to disable automatic placement.
+-- @propertytype string The name of an `awful.placement` function, like `"next_to"`.
 -- @propemits true false
 -- @see awful.placement
 
@@ -494,6 +523,4 @@ local function create_popup(_, args)
     return w
 end
 
---@DOC_wibox_COMMON@
-
 return setmetatable(module, {__call = create_popup})

lib/awful/prompt.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- Prompt module for awful.
+--- Convert a `wibox.widget.textbox` into an input prompt.
 --
 -- **Keyboard navigation**:
 --
@@ -444,23 +444,24 @@ end
 --         return command
 --       end}
 --     }
--- @param textbox The textbox to use for the prompt. [**DEPRECATED**]
--- @param exe_callback The callback function to call with command as argument
+-- @tparam wibox.widget.textbox textbox The textbox to use for the prompt. [**DEPRECATED**]
+-- @tparam[opt] function|nil exe_callback The callback function to call with command as argument
 -- when finished. [**DEPRECATED**]
--- @param completion_callback The callback function to call to get completion.
+-- @tparam[opt] function completion_callback The callback function to call to get completion.
 --   [**DEPRECATED**]
--- @param[opt] history_path File path where the history should be
+-- @tparam[opt] string history_path File path where the history should be
 -- saved, set nil to disable history [**DEPRECATED**]
--- @param[opt] history_max Set the maximum entries in history
+-- @tparam[opt] number history_max Set the maximum entries in history
 -- file, 50 by default [**DEPRECATED**]
--- @param[opt] done_callback The callback function to always call
+-- @tparam[opt] function done_callback The callback function to always call
 -- without arguments, regardless of whether the prompt was cancelled.
 --  [**DEPRECATED**]
--- @param[opt] changed_callback The callback function to call
+-- @tparam[opt] function changed_callback The callback function to call
 -- with command as argument when a command was changed. [**DEPRECATED**]
--- @param[opt] keypressed_callback The callback function to call
+-- @tparam[opt] function keypressed_callback The callback function to call
 --   with mod table, key and command as arguments when a key was pressed.
 --   [**DEPRECATED**]
+-- @noreturn
 -- @see gears.color
 -- @staticfct awful.prompt.run
 function prompt.run(args, textbox, exe_callback, completion_callback,

lib/awful/screen.lua

@@ -49,10 +49,10 @@ end
 
 --- Get the square distance between a `screen` and a point.
 -- @deprecated awful.screen.getdistance_sq
--- @param s Screen
--- @param x X coordinate of point
--- @param y Y coordinate of point
--- @return The squared distance of the screen to the provided point.
+-- @tparam screen s Screen
+-- @tparam integer x X coordinate of point
+-- @tparam integer y Y coordinate of point
+-- @treturn number The squared distance of the screen to the provided point.
 -- @see screen.get_square_distance
 function screen.getdistance_sq(s, x, y)
     gdebug.deprecate("Use s:get_square_distance(x, y) instead of awful.screen.getdistance_sq", {deprecated_in=4})
@@ -90,7 +90,8 @@ end
 -- This moves the mouse pointer to the last known position on the new screen,
 -- or keeps its position relative to the current focused screen.
 -- @staticfct awful.screen.focus
--- @tparam screen _screen Screen number (defaults / falls back to mouse.screen).
+-- @tparam screen screen Screen number (defaults / falls back to mouse.screen).
+-- @treturn screen The newly focused screen.
 -- @request client activate screen.focus granted The most recent focused client
 --  for this screen should be re-activated.
 function screen.focus(_screen)
@@ -126,6 +127,8 @@ function screen.focus(_screen)
     if c then
         c:emit_signal("request::activate", "screen.focus", {raise=false})
     end
+
+    return _screen
 end
 
 --- Get the next screen in a specific direction.
@@ -134,8 +137,8 @@ end
 -- the specified direction.
 --
 -- @method get_next_in_direction
--- @param self Screen.
--- @param dir The direction, can be either "up", "down", "left" or "right".
+-- @tparam string dir The direction, can be either "up", "down", "left" or "right".
+-- @treturn screen The next screen.
 function screen.object.get_next_in_direction(self, dir)
     local sel = get_screen(self)
     if not sel then
@@ -156,7 +159,8 @@ end
 -- or keeps its position relative to the current focused screen.
 -- @staticfct awful.screen.focus_bydirection
 -- @tparam string dir The direction, can be either "up", "down", "left" or "right".
--- @tparam screen s Screen.
+-- @tparam[opt=awful.screen.focused()] screen s Screen.
+-- @treturn screen The next screen.
 function screen.focus_bydirection(dir, s)
     local sel = get_screen(s or screen.focused())
     local target = sel:get_next_in_direction(dir)
@@ -174,6 +178,7 @@ end
 -- @staticfct awful.screen.focus_relative
 -- @tparam int offset Value to add to the current focused screen index. 1 to
 --   focus the next one, -1 to focus the previous one.
+-- @treturn screen The newly focusd screen.
 function screen.focus_relative(offset)
     return screen.focus(gmath.cycle(capi.screen.count(),
                                    screen.focused().index + offset))
@@ -193,6 +198,8 @@ end
 -- @tparam number tiling_area.y
 -- @tparam number tiling_area.width
 -- @tparam number tiling_area.height
+-- @propertydefault This is the `workarea` substracted with the `padding` area.
+-- @propertyunit pixel
 -- @readonly
 -- @see padding
 -- @see get_bounding_geometry
@@ -209,8 +216,13 @@ end
 -- Reading this property returns a screenshot of the physical
 -- (Xinerama) screen as a cairo surface.
 --
+-- Use `gears.surface(c.content)` to convert the raw content into a static image.
+--
 -- @property content
--- @tparam gears.surface content
+-- @tparam raw_surface content
+-- @propertydefault The client raw pixels at the time the property is called.
+--  If there is no compositing manager running, it might be black.
+-- @see gears.surface
 -- @readonly
 
 function screen.object.get_content(s)
@@ -228,8 +240,8 @@ end
 --- Get or set the screen padding.
 --
 -- @deprecated awful.screen.padding
--- @param s The screen object to change the padding on
--- @param[opt=nil] padding The padding, a table with 'top', 'left', 'right' and/or
+-- @tparam screen s The screen object to change the padding on.
+-- @tparam[opt=nil] table|integer|nil padding The padding, a table with 'top', 'left', 'right' and/or
 -- 'bottom' or a number value to apply set the same padding on all sides. Can be
 --  nil if you only want to retrieve padding
 -- @treturn table A table with left, right, top and bottom number values.
@@ -246,18 +258,19 @@ end
 --
 -- This adds a "buffer" section on each side of the screen.
 --
--- **Signal:**
---
--- * *property::padding*
---
 -- @DOC_screen_padding_EXAMPLE@
 --
 -- @property padding
--- @param table
--- @tfield integer table.left The padding on the left.
--- @tfield integer table.right The padding on the right.
--- @tfield integer table.top The padding on the top.
--- @tfield integer table.bottom The padding on the bottom.
+-- @tparam[opt=0] table|number padding
+-- @tparam[opt=0] integer padding.left The padding on the left.
+-- @tparam[opt=0] integer padding.right The padding on the right.
+-- @tparam[opt=0] integer padding.top The padding on the top.
+-- @tparam[opt=0] integer padding.bottom The padding on the bottom.
+-- @negativeallowed false
+-- @propertyunit pixel
+-- @propertytype number A single value for each sides.
+-- @propertytype table A different value for each sides.
+-- @propemits true false
 -- @usebeautiful beautiful.maximized_honor_padding Honor the screen padding when maximizing.
 
 function screen.object.get_padding(self)
@@ -299,18 +312,18 @@ end
 --        -- do something
 --    end
 --
--- **Signal:**
---
---  * *property::outputs*
---
 -- @property outputs
--- @param table
--- @tfield table table.name A table with the screen name as key (like `eDP1` on a laptop)
--- @tfield integer table.mm_width The screen physical width.
--- @tfield integer table.mm_height The screen physical height.
--- @tfield integer table.name The output name.
--- @tfield integer table.viewport_id The identifier of the viewport this output
+-- @tparam table outputs
+-- @tablerowtype A key-value table with the output name as key and a table of
+--  metadata as value.
+-- @tablerowkey integer mm_width The screen physical width.
+-- @tablerowkey integer mm_height The screen physical height.
+-- @tablerowkey string name The output name.
+-- @tablerowkey string viewport_id The identifier of the viewport this output
 --  corresponds to.
+-- @propertydefault This may or may not be populated if the screen are based on
+--  an actual physical screen. For fake screen, this property content is undefined.
+-- @propemits true false
 -- @readonly
 
 function screen.object.get_outputs(s)
@@ -379,7 +392,7 @@ end
 --
 -- This method computes the different variants of the "usable" screen geometry.
 --
--- @staticfct screen.get_bounding_geometry
+-- @method screen.get_bounding_geometry
 -- @tparam[opt={}] table args The arguments
 -- @tparam[opt=false] boolean args.honor_padding Whether to honor the screen's padding.
 -- @tparam[opt=false] boolean args.honor_workarea Whether to honor the screen's workarea.
@@ -439,7 +452,8 @@ end
 -- default.
 --
 -- @property clients
--- @param table The clients list, ordered from top to bottom.
+-- @tparam[opt={}] table clients The clients list, ordered from top to bottom.
+-- @tablerowtype A list of `client` objects.
 -- @see all_clients
 -- @see hidden_clients
 -- @see client.get
@@ -467,7 +481,8 @@ end
 -- This includes minimized clients and clients on hidden tags.
 --
 -- @property hidden_clients
--- @param table The clients list, ordered from top to bottom.
+-- @tparam[opt={}] table hidden_clients The clients list, ordered from top to bottom.
+-- @tablerowtype A list of `client` objects.
 -- @see clients
 -- @see all_clients
 -- @see client.get
@@ -486,7 +501,8 @@ end
 --- All clients assigned to the screen.
 --
 -- @property all_clients
--- @param table The clients list, ordered from top to bottom.
+-- @tparam[opt={}] table all_clients The clients list, ordered from top to bottom.
+-- @tablerowtype A list of `client` objects.
 -- @see clients
 -- @see hidden_clients
 -- @see client.get
@@ -513,7 +529,8 @@ end
 -- @DOC_screen_tiled_clients_EXAMPLE@
 --
 -- @property tiled_clients
--- @param table The clients list, ordered from top to bottom.
+-- @tparam[opt={}] table tiled_clients The clients list, ordered from top to bottom.
+-- @tablerowtype A list of `client` objects.
 
 --- Get tiled clients for the screen.
 --
@@ -541,6 +558,7 @@ end
 -- @staticfct awful.screen.connect_for_each_screen
 -- @tparam function func The function to call.
 -- @tparam screen func.screen The screen.
+-- @noreturn
 function screen.connect_for_each_screen(func)
     for s in capi.screen do
         func(s)
@@ -548,9 +566,10 @@ function screen.connect_for_each_screen(func)
     capi.screen.connect_signal("added", func)
 end
 
---- Undo the effect of connect_for_each_screen.
+--- Undo the effect of `awful.screen.connect_for_each_screen`.
 -- @staticfct awful.screen.disconnect_for_each_screen
 -- @tparam function func The function that should no longer be called.
+-- @noreturn
 function screen.disconnect_for_each_screen(func)
     capi.screen.disconnect_signal("added", func)
 end
@@ -561,8 +580,8 @@ end
 -- `awful.tag.new` or `t:delete()` to alter this list.
 --
 -- @property tags
--- @param table
--- @treturn table A table with all available tags.
+-- @tparam[opt={}] table tags
+-- @tablerowtype A table with all available tags.
 -- @readonly
 
 function screen.object.get_tags(s, unordered)
@@ -585,8 +604,8 @@ end
 
 --- A list of all selected tags on the screen.
 -- @property selected_tags
--- @param table
--- @treturn table A table with all selected tags.
+-- @tparam[opt={}] table selected_tags
+-- @tablerowtype A table with all selected tags.
 -- @readonly
 -- @see tag.selected
 -- @see client.to_selected_tags
@@ -605,8 +624,7 @@ end
 
 --- The first selected tag.
 -- @property selected_tag
--- @param tag
--- @treturn ?tag The first selected tag or nil.
+-- @tparam[opt=nil] tag|nil selected_tag
 -- @readonly
 -- @see tag.selected
 -- @see selected_tags
@@ -651,10 +669,14 @@ end
 --
 -- @DOC_awful_screen_split2_EXAMPLE@
 --
--- @tparam[opt] table ratios The different ratios to split into. If none is
---  provided, it is split in half.
+-- @tparam[opt={50﹐50}] table ratios The different ratios to split into. If none
+--  is provided, it is split in half.
 -- @tparam[opt] string mode Either "vertical" or "horizontal". If none is
 --  specified, it will split along the longest axis.
+-- @treturn table A table with the screen objects. The first value is the
+--  original screen object (`s`) and the following one(s) are the new screen
+--  objects. The values are ordered from left to right or top to bottom depending
+--  on the value of `mode`.
 -- @method split
 function screen.object.split(s, ratios, mode, _geo)
     s = get_screen(s)
@@ -736,6 +758,7 @@ end
 -- defaulting to 96.
 --
 -- @tparam boolean enabled Enable or disable automatic DPI support.
+-- @noreturn
 -- @staticfct awful.screen.set_auto_dpi_enabled
 function screen.set_auto_dpi_enabled(enabled)
     for s in capi.screen do
@@ -753,16 +776,24 @@ end
 -- screen is duplicated on a projector).
 --
 -- @property dpi
--- @param number the DPI value.
+-- @tparam[opt=96] number dpi
+-- @propertyunit pixel\_per\_inch
+-- @negativeallowed false
 
 --- The lowest density DPI from all of the (physical) outputs.
 -- @property minimum_dpi
--- @param number the DPI value.
+-- @tparam number minimum_dpi
+-- @propertyunit pixel\_per\_inch
+-- @propertydefault This is extracted from `outputs`.
+-- @negativeallowed false
 -- @readonly
 
 --- The highest density DPI from all of the (physical) outputs.
 -- @property maximum_dpi
--- @param number the DPI value.
+-- @tparam number maximum_dpi
+-- @propertydefault This is extracted from `outputs`.
+-- @propertyunit pixel\_per\_inch
+-- @negativeallowed false
 -- @readonly
 
 --- The preferred DPI from all of the (physical) outputs.
@@ -771,28 +802,42 @@ end
 -- the lowest of the resulting virtual DPIs.
 --
 -- @property preferred_dpi
--- @param number the DPI value.
+-- @tparam number preferred_dpi
+-- @propertydefault This is extracted from `outputs`.
+-- @negativeallowed false
 -- @readonly
 
 --- The maximum diagonal size in millimeters.
 --
 -- @property mm_maximum_size
--- @param number
+-- @tparam number mm_maximum_size
+-- @propertydefault This is extracted from `outputs`.
+-- @propertyunit millimeter
+-- @negativeallowed false
 
 --- The minimum diagonal size in millimeters.
 --
 -- @property mm_minimum_size
--- @param number
+-- @tparam number mm_minimum_size
+-- @propertydefault This is extracted from `outputs`.
+-- @propertyunit millimeter
+-- @negativeallowed false
 
 --- The maximum diagonal size in inches.
 --
 -- @property inch_maximum_size
--- @param number
+-- @tparam number inch_maximum_size
+-- @propertydefault This is extracted from `outputs`.
+-- @propertyunit inch
+-- @negativeallowed false
 
 --- The minimum diagonal size in inches.
 --
 -- @property inch_minimum_size
--- @param number
+-- @tparam number inch_minimum_size
+-- @propertydefault This is extracted from `outputs`.
+-- @propertyunit inch
+-- @negativeallowed false
 
 --- Emitted when a new screen is added.
 --
@@ -952,6 +997,8 @@ end
 -- `request::remove` and `request::resize`.
 --
 -- @signalhandler awful.screen.create_screen_handler
+-- @tparam table viewport
+-- @sourcesignal screen request::create
 -- @see request::create
 
 --- Default handler for `request::remove`.
@@ -971,6 +1018,8 @@ end
 --    end
 --
 -- @signalhandler awful.screen.remove_screen_handler
+-- @tparam table viewport
+-- @sourcesignal screen request::remove
 -- @see request::remove
 
 --- Default handler for `request::resize`.
@@ -992,6 +1041,8 @@ end
 --    end
 --
 -- @signalhandler awful.screen.resize_screen_handler
+-- @tparam table viewport
+-- @sourcesignal screen request::resize
 -- @see request::resize
 
 -- Add the DPI properties.

lib/awful/spawn.lua

@@ -1,7 +1,7 @@
 --luacheck: no max line length
 
 ---------------------------------------------------------------------------
---- Spawning of programs.
+--- Spawn sub-processes and optionally get their output.
 --
 -- This module provides methods to start programs and supports startup
 -- notifications, which allows for callbacks and applying properties to the
@@ -364,6 +364,10 @@ end
 --- Spawn a program using the shell.
 -- This calls `cmd` with `$SHELL -c` (via `awful.util.shell`).
 -- @tparam string cmd The command.
+-- @treturn[1] integer The forked PID.
+-- @treturn[1] ?string The startup notification ID, if `sn` is not false, or
+--   a `callback` is provided.
+-- @treturn[2] string Error message.
 -- @staticfct awful.spawn.with_shell
 function spawn.with_shell(cmd)
     if cmd and cmd ~= "" then
@@ -500,6 +504,7 @@ end
 -- @tparam[opt] function done_callback Function that is called when the
 --   operation finishes (e.g. due to end of file).
 -- @tparam[opt=false] boolean close Should the stream be closed after end-of-file?
+-- @noreturn
 -- @staticfct awful.spawn.read_lines
 function spawn.read_lines(input_stream, line_callback, done_callback, close)
     local stream = Gio.DataInputStream.new(input_stream)
@@ -649,8 +654,9 @@ end
 -- @tparam[opt] string unique_id A string to identify the client so it isn't executed
 --  multiple time.
 -- @tparam[opt] function callback A callback function when the client is created.
--- @see ruled.client
+-- @noreturn
 -- @staticfct awful.spawn.once
+-- @see ruled.client
 function spawn.once(cmd, rules, matcher, unique_id, callback)
     local hash = unique_id or hash_command(cmd, rules)
     local status = register_common(hash, rules, matcher, callback)
@@ -682,8 +688,9 @@ end
 -- @tparam[opt] string unique_id A string to identify the client so it isn't executed
 --  multiple time.
 -- @tparam[opt] function callback A callback function when the client is created.
--- @see ruled.client
+-- @noreturn
 -- @staticfct awful.spawn.single_instance
+-- @see ruled.client
 function spawn.single_instance(cmd, rules, matcher, unique_id, callback)
     local hash = unique_id or hash_command(cmd, rules)
     register_common(hash, rules, matcher, callback)

lib/awful/tag.lua

@@ -149,6 +149,8 @@ end
 --
 -- @property index
 -- @tparam integer index
+-- @propertydefault This is based on the current list of `t.screen:tags()`.
+-- @negativeallowed false
 -- @propemits false false
 
 function tag.object.set_index(self, idx)
@@ -203,11 +205,10 @@ function tag.object.get_index(query_tag)
     end
 end
 
---- Move a tag to an absolute position in the screen[]:tags() table.
+--- Move a tag to an absolute position in the `screen[]:tags()` table.
 -- @deprecated awful.tag.move
--- @param new_index Integer absolute position in the table to insert.
--- @param target_tag The tag that should be moved. If null, the currently
--- selected tag is used.
+-- @tparam integer new_index Integer absolute position in the table to insert.
+-- @tparam[opt=awful.screen.focused().selected_tag] tag target_tag The tag that should be moved.
 -- @see index
 function tag.move(new_index, target_tag)
     gdebug.deprecate("Use t.index = new_index instead of awful.tag.move", {deprecated_in=4})
@@ -222,6 +223,7 @@ end
 --
 -- @method swap
 -- @tparam tag tag2 The second tag
+-- @noreturn
 -- @see client.swap
 function tag.object.swap(self, tag2)
     local idx1, idx2 = tag.object.get_index(self), tag.object.get_index(tag2)
@@ -243,8 +245,8 @@ end
 --- Swap 2 tags
 -- @deprecated awful.tag.swap
 -- @see tag.swap
--- @param tag1 The first tag
--- @param tag2 The second tag
+-- @tparam tag tag1 The first tag
+-- @tparam tag tag2 The second tag
 function tag.swap(tag1, tag2)
     gdebug.deprecate("Use t:swap(tag2) instead of awful.tag.swap", {deprecated_in=4})
 
@@ -263,7 +265,7 @@ end
 -- @constructorfct awful.tag.add
 -- @tparam string name The tag name, a string
 -- @tparam[opt=nil] table|nil props The tags initial properties, a table
--- @return The created tag
+-- @treturn tag The created tag.
 -- @see tag.delete
 function tag.add(name, props)
     local properties = props or {}
@@ -308,7 +310,7 @@ end
 --
 -- @staticfct awful.tag.new
 -- @tparam table names The tag name, in a table
--- @tparam[opt=1] screen|number screen The tag screen (defaults to screen 1).
+-- @tparam[opt=1] screen|number screen The tag screen.
 -- @tparam table layout The layout or layout table to set for this tags by default.
 -- @treturn table A table with all created tags.
 function tag.new(names, screen, layout)
@@ -334,8 +336,9 @@ end
 
 --- Find a suitable fallback tag.
 -- @staticfct awful.tag.find_fallback
--- @tparam screen screen The screen to look for a tag on. [awful.screen.focused()]
--- @tparam[opt=nil] table|nil invalids A table of tags considered unacceptable. [selectedlist(scr)]
+-- @tparam[opt=awful.screen.focused()] screen screen The screen to look for a tag on.
+-- @tparam[opt=nil] table|nil invalids A table of tags considered unacceptable.
+-- @treturn tag|nil Returns a fallback tag if one was found, otherwise `nil`.
 function tag.find_fallback(screen, invalids)
     local scr = screen or ascreen.focused()
     local t = invalids or scr.selected_tags
@@ -357,6 +360,7 @@ end
 -- @tparam table args The arguments.
 -- @tparam tag args.fallback_tag A fallback tag.
 -- @tparam[opt=false] boolean args.allow_untagged Allow the untagged clients to remain untagged.
+-- @noreturn
 -- @emits cleared After all clients have been untagged.
 -- @emits untagged For each currently tagged clients.
 -- @emitstparam untagged client c The untagged client.
@@ -397,7 +401,7 @@ end
 --  stickied tags to.
 -- @tparam[opt=false] boolean force Move even non-sticky clients to the fallback
 -- tag.
--- @return Returns true if the tag is successfully deleted.
+-- @treturn boolean Returns true if the tag is successfully deleted.
 -- If there are no clients exclusively on this tag then delete it. Any
 -- stickied clients are assigned to the optional 'fallback_tag'.
 -- If after deleting the tag there is no selected tag, try and restore from
@@ -465,9 +469,9 @@ end
 --- Delete a tag.
 -- @deprecated awful.tag.delete
 -- @see tag.delete
--- @param target_tag Optional tag object to delete. [selected()]
--- @param fallback_tag Tag to assign stickied tags to. [~selected()]
--- @return Returns true if the tag is successfully deleted, nil otherwise.
+-- @tparam[opt=mouse.screen.selected_tag] tag target_tag Optional tag object to delete.
+-- @tparam[opt] tag|nil fallback_tag Tag to assign stickied tags to.
+-- @treturn boolean Returns true if the tag is successfully deleted, nil otherwise.
 -- If there are no clients exclusively on this tag then delete it. Any
 -- stickied clients are assigned to the optional 'fallback_tag'.
 -- If after deleting the tag there is no selected tag, try and restore from
@@ -481,6 +485,7 @@ end
 --- Update the tag history.
 -- @staticfct awful.tag.history.update
 -- @tparam screen obj Screen object.
+-- @noreturn
 function tag.history.update(obj)
     local s = get_screen(obj)
     local curtags = s.selected_tags
@@ -521,6 +526,7 @@ end
 
 --- Revert tag history.
 -- @staticfct awful.tag.history.restore
+-- @noreturn
 -- @tparam screen screen The screen.
 -- @tparam number idx Index in history. Defaults to "previous" which is a special index
 -- toggling between last two selected sets of tags. Number (eg 1) will go back
@@ -558,7 +564,7 @@ end
 --- Get a list of all tags on a screen
 -- @deprecated awful.tag.gettags
 -- @tparam screen s Screen
--- @return A table with all available tags
+-- @treturn table A table with all available tags
 -- @see screen.tags
 function tag.gettags(s)
     gdebug.deprecate("Use s.tags instead of awful.tag.gettags", {deprecated_in=4})
@@ -571,7 +577,7 @@ end
 --- Find a tag by name.
 -- @tparam screen s The screen of the tag
 -- @tparam string name The name of the tag
--- @return The tag found, or `nil`
+-- @treturn tag|nil The tag found, or `nil`
 -- @staticfct awful.tag.find_by_name
 -- @usage -- For the current screen
 -- local t = awful.tag.find_by_name(awful.screen.focused(), "name")
@@ -594,7 +600,7 @@ end
 --- The tag screen.
 --
 -- @property screen
--- @tparam screen screen
+-- @tparam[opt=awful.screen.focused()] screen screen
 -- @propemits false false
 -- @see screen
 
@@ -637,8 +643,8 @@ end
 --- Set a tag's screen
 -- @deprecated awful.tag.setscreen
 -- @see screen
--- @param s Screen
--- @param t tag object
+-- @tparam screen s Screen
+-- @tparam tag t The tag object
 function tag.setscreen(s, t)
     -- For API consistency, the arguments have been swapped for Awesome 3.6
     -- this method is already deprecated, so be silent and swap the args
@@ -654,8 +660,8 @@ end
 --- Get a tag's screen
 -- @deprecated awful.tag.getscreen
 -- @see screen
--- @param[opt] t tag object
--- @return Screen number
+-- @tparam[opt=awful.screen.focused().selected_taga] tag|nil t Tag object
+-- @treturn screen The tag screen.
 function tag.getscreen(t)
     gdebug.deprecate("Use t.screen instead of awful.tag.getscreen(t)", {deprecated_in=4})
 
@@ -668,8 +674,8 @@ end
 
 --- Return a table with all visible tags
 -- @deprecated awful.tag.selectedlist
--- @param s Screen.
--- @return A table with all selected tags.
+-- @tparam screen s Screen.
+-- @treturn table A table with all selected tags.
 -- @see screen.selected_tags
 function tag.selectedlist(s)
     gdebug.deprecate("Use s.selected_tags instead of awful.tag.selectedlist", {deprecated_in=4})
@@ -681,7 +687,7 @@ end
 
 --- Return only the first visible tag.
 -- @deprecated awful.tag.selected
--- @param s Screen.
+-- @tparam screen s Screen.
 -- @see screen.selected_tag
 function tag.selected(s)
     gdebug.deprecate("Use s.selected_tag instead of awful.tag.selected", {deprecated_in=4})
@@ -694,7 +700,7 @@ end
 --- The default master width factor
 --
 -- @beautiful beautiful.master_width_factor
--- @param number (default: 0.5)
+-- @tparam[opt=0.5] number master_width_factor
 -- @see master_width_factor
 -- @see gap
 
@@ -714,7 +720,9 @@ end
 -- @DOC_screen_mwfact2_EXAMPLE@
 --
 -- @property master_width_factor
--- @tparam number master_width_factor Between 0 and 1
+-- @tparam[opt=beautiful.master_width_factor] number master_width_factor
+-- @rangestart 0.0
+-- @rangestop 1.0
 -- @emits property::mwfact When the value changes (deprecated).
 -- @emits property::master_width_factor When the value changes.
 -- @see master_count
@@ -740,8 +748,8 @@ end
 -- @deprecated awful.tag.setmwfact
 -- @see master_fill_policy
 -- @see master_width_factor
--- @param mwfact Master width factor.
--- @param t The tag to modify, if null tag.selected() is used.
+-- @tparam number mwfact Master width factor.
+-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify.
 function tag.setmwfact(mwfact, t)
     gdebug.deprecate("Use t.master_width_factor = mwfact instead of awful.tag.setmwfact", {deprecated_in=4})
 
@@ -752,7 +760,8 @@ end
 -- @staticfct awful.tag.incmwfact
 -- @see master_width_factor
 -- @tparam number add Value to add to master width factor.
--- @tparam tag t The tag to modify, if null tag.selected() is used.
+-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify.
+-- @noreturn
 function tag.incmwfact(add, t)
     t = t or t or ascreen.focused().selected_tag
     tag.object.set_master_width_factor(t, tag.object.get_master_width_factor(t) + add)
@@ -762,7 +771,7 @@ end
 -- @deprecated awful.tag.getmwfact
 -- @see master_width_factor
 -- @see master_fill_policy
--- @param[opt] t The tag.
+-- @tparam[opt] tag|nil t The tag.
 function tag.getmwfact(t)
     gdebug.deprecate("Use t.master_width_factor instead of awful.tag.getmwfact", {deprecated_in=4})
 
@@ -795,6 +804,11 @@ end
 --     }
 --
 -- @tfield table awful.tag.layouts
+-- @tparam[opt={}] table awful.tag.layouts
+-- @see request::layouts
+-- @see awful.layout.append_default_layouts
+-- @see awful.layout.append_default_layout
+-- @see awful.layout.remove_default_layout
 
 --- The tag client layout.
 --
@@ -817,6 +831,34 @@ end
 --     placed. The only parameter is a table or arguments returned by
 --     `awful.layout.parameters`
 --
+-- The parameter table contains:
+--
+-- <table class='widget_list' border=1>
+--  <tr style='font-weight: bold;'>
+--   <th align='center'>Parameter </th>
+--   <th align='center'>Type</th>
+--   <th align='center'>Description</th>
+--  </tr>
+--  <tr><td>`workarea`</td><td> table </td><td>
+--   A table with `x`,`y`, `width` and `height` keys.<br/>
+--   All clients must be placed within this area.
+--  </td></tr>
+--  <tr><td align='center'>`geometry`</td><td> table </td><td>A table with the screen geometry.</td></tr>
+--  <tr><td align='center'>`clients`</td><td> table </td><td>A list of the clients to place.</td></tr>
+--  <tr><td align='center'>`screen`</td><td> screen </td><td>The screen.</td></tr>
+--  <tr><td align='center'>`padding`</td><td> table </td><td>
+--   A table with `left`, `right`, `top` and `bottom` keys.
+--  </td></tr>
+--  <tr>
+--   <td align='center'>`useless_gap`</td><td> integer </td>
+--   <td>The space that will be removed from the clients.</td>
+--  </tr>
+--  <tr><td align='center'>`geometries`</td><td> table </td><td>
+--   Empty. Place the client as key and preferred geometry<br/>
+--   as value. Do not call `:geometry()` directly.
+--  </td></tr>
+-- </table>
+--
 -- **Stateful layouts:**
 --
 -- The stateful layouts API is the same as stateless, but they are a function
@@ -833,9 +875,13 @@ end
 --
 -- @property layout
 -- @tparam layout|function layout A layout table or a constructor function
+-- @propertydefault The first non-nil value of either `self.layouts[1]` or
+-- `awful.layout.layouts[1]` or `awful.layout.suit.floating`.
+-- @functionparam table params A table containing the state of the layout (see the table above).
+-- @functionnoreturn
 -- @propemits false false
 -- @see awful.tag.layouts
--- @return The layout
+-- @see awful.layout.parameters
 
 --- The (proposed) list of available layouts for this tag.
 --
@@ -849,10 +895,13 @@ end
 -- front of the list.
 --
 -- @property layouts
--- @tparam table layouts
+-- @tparam[opt=nil] table|nil layouts
+-- @propertytype nil Use the current value of `awful.layout.layouts`.
 -- @request tag layouts awful granted When the `layouts` property is first called
 --  and there is no layouts, then that signal is called.
 -- @see awful.layout.layouts
+-- @see screen.workarea
+-- @see screen.padding
 -- @see layout
 
 function tag.object.set_layout(t, layout)
@@ -1002,8 +1051,8 @@ end
 --- Set layout.
 -- @deprecated awful.tag.setlayout
 -- @see layout
--- @param layout a layout table or a constructor function
--- @param t The tag to modify
+-- @param layout A layout table or a constructor function
+-- @tparam tag t The tag to modify
 -- @return The layout
 function tag.setlayout(layout, t)
     gdebug.deprecate("Use t.layout = layout instead of awful.tag.setlayout", {deprecated_in=4})
@@ -1043,7 +1092,7 @@ end
 -- the "Non-volatile" tag is still there (but with zero clients).
 --
 -- @property volatile
--- @tparam boolean volatile
+-- @tparam[opt=false] boolean volatile
 -- @propemits false false
 -- @see delete
 
@@ -1053,7 +1102,7 @@ end
 -- @deprecated awful.tag.setvolatile
 -- @see volatile
 -- @tparam boolean volatile If the tag must be deleted when the last client is untagged
--- @param t The tag to modify, if null tag.selected() is used.
+-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify.
 function tag.setvolatile(volatile, t)
     gdebug.deprecate("Use t.volatile = volatile instead of awful.tag.setvolatile", {deprecated_in=4})
 
@@ -1063,7 +1112,7 @@ end
 --- Get if the tag must be deleted when the last client closes
 -- @deprecated awful.tag.getvolatile
 -- @see volatile
--- @param t The tag to modify, if null tag.selected() is used.
+-- @tparam[opt=opt=awful.screen.focused().selected_tag] tag t The tag to modify.
 -- @treturn boolean If the tag will be deleted when the last client is untagged
 function tag.getvolatile(t)
     gdebug.deprecate("Use t.volatile instead of awful.tag.getvolatile", {deprecated_in=4})
@@ -1074,7 +1123,7 @@ end
 --- The default gap.
 --
 -- @beautiful beautiful.useless_gap
--- @param number (default: 0)
+-- @tparam[opt=0] number useless_gap
 -- @see gap
 -- @see gap_single_client
 
@@ -1092,7 +1141,9 @@ end
 -- @DOC_screen_gaps2_EXAMPLE@
 --
 -- @property gap
--- @tparam number gap The value has to be greater than zero.
+-- @tparam[opt=beautiful.useless_gap] integer gap The value has to be greater than zero.
+-- @propertyunit pixel
+-- @negativeallowed false
 -- @emits property::useless_gap When the gap changes.
 -- @see gap_single_client
 -- @see awful.tag.incgap
@@ -1112,8 +1163,8 @@ end
 --- Set the spacing between clients
 -- @deprecated awful.tag.setgap
 -- @see gap
--- @param useless_gap The spacing between clients
--- @param t The tag to modify, if null tag.selected() is used.
+-- @tparam number|nil useless_gap The spacing between clients
+-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify.
 function tag.setgap(useless_gap, t)
     gdebug.deprecate("Use t.gap = useless_gap instead of awful.tag.setgap", {deprecated_in=4})
 
@@ -1122,9 +1173,11 @@ end
 
 --- Increase the spacing between clients
 -- @staticfct awful.tag.incgap
--- @see gap
 -- @tparam number add Value to add to the spacing between clients
--- @tparam tag t The tag to modify, if null tag.selected() is used.
+-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify.
+-- @noreturn
+-- @see gap
+-- @see beautiful.useless_gap
 function tag.incgap(add, t)
     t = t or t or ascreen.focused().selected_tag
     tag.object.set_gap(t, tag.object.get_gap(t) + add)
@@ -1133,7 +1186,7 @@ end
 --- Enable gaps for a single client.
 --
 -- @beautiful beautiful.gap_single_client
--- @param boolean (default: true)
+-- @tparam[opt=true] boolean gap_single_client
 -- @see gap
 -- @see gap_single_client
 
@@ -1153,7 +1206,7 @@ end
 -- @DOC_screen_gap_single_client_false_EXAMPLE@
 --
 -- @property gap_single_client
--- @tparam boolean gap_single_client Enable gaps for a single client
+-- @tparam[opt=beautiful.gap_single_client] boolean gap_single_client Enable gaps for a single client
 -- @propemits false false
 -- @see awful.tag.incgap
 
@@ -1199,7 +1252,7 @@ end
 --   `master_width_factor`
 --
 -- @beautiful beautiful.master_fill_policy
--- @param string (default: "expand")
+-- @tparam[opt="expand"] string master_fill_policy
 -- @see master_fill_policy
 
 --- Set size fill policy for the master client(s).
@@ -1207,12 +1260,6 @@ end
 -- Some multi-column layouts can be configured so that the space is
 -- redistributed when there is not enough clients to fill all columns.
 --
--- ** Possible values**:
---
--- * *expand*: Take all the space
--- * *master\_width\_factor*: Only take the ratio defined by the
---   `master_width_factor`
---
 -- This is the default behavior of the `tile.left` layout (*expand*):
 --
 -- @DOC_screen_mfpol2_EXAMPLE@
@@ -1225,7 +1272,10 @@ end
 -- redistributed on both side.
 --
 -- @property master_fill_policy
--- @tparam string master_fill_policy "expand" or "master_width_factor"
+-- @tparam[opt=beautiful.master_fill_policy] string master_fill_policy
+-- @propertyvalue "expand" Take all the space
+-- @propertyvalue "master_width_factor" Only take the ratio defined by the
+--   `master_width_factor`
 -- @propemits false false
 -- @see awful.tag.togglemfpol
 
@@ -1240,8 +1290,9 @@ end
 -- @see master_fill_policy
 -- @tparam string policy Can be set to
 -- "expand" (fill all the available workarea) or
--- "master_width_factor" (fill only an area inside the master width factor)
+-- `master_width_factor` (fill only an area inside the master width factor)
 -- @tparam[opt=tag.selected()] tag t The tag to modify
+-- @noreturn
 function tag.setmfpol(policy, t)
     gdebug.deprecate("Use t.master_fill_policy = policy instead of awful.tag.setmfpol", {deprecated_in=4})
 
@@ -1250,10 +1301,11 @@ function tag.setmfpol(policy, t)
 end
 
 --- Toggle size fill policy for the master client(s)
--- between "expand" and "master_width_factor".
+-- between "expand" and `master_width_factor`.
 -- @staticfct awful.tag.togglemfpol
+-- @noreturn
 -- @see master_fill_policy
--- @tparam tag t The tag to modify, if null tag.selected() is used.
+-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify.
 function tag.togglemfpol(t)
     t = t or ascreen.focused().selected_tag
 
@@ -1283,7 +1335,7 @@ end
 --- The default number of master windows.
 --
 -- @beautiful beautiful.master_count
--- @param integer (default: 1)
+-- @tparam[opt=1] integer master_count
 -- @see master_count
 
 --- Set the number of master windows.
@@ -1291,7 +1343,8 @@ end
 -- @DOC_sequences_tag_master_count_EXAMPLE@
 --
 -- @property master_count
--- @tparam integer master_count nmaster Only positive values are accepted
+-- @tparam[opt=beautiful.master_count] integer master_count Only positive values are accepted
+-- @rangestart 1
 -- @emits property::nmaster Deprecated.
 -- @emits property::master_count When the value changes.
 -- @see awful.tag.incnmaster
@@ -1312,8 +1365,8 @@ end
 --- The number of master clients.
 -- @deprecated awful.tag.setnmaster
 -- @see master_count
--- @param nmaster The number of master windows.
--- @param[opt] t The tag.
+-- @tparam number nmaster The number of master windows.
+-- @tparam[opt] tag t The tag.
 function tag.setnmaster(nmaster, t)
     gdebug.deprecate("Use t.master_count = nmaster instead of awful.tag.setnmaster", {deprecated_in=4})
 
@@ -1323,7 +1376,7 @@ end
 --- Get the number of master windows.
 -- @deprecated awful.tag.getnmaster
 -- @see master_count
--- @param[opt] t The tag.
+-- @tparam[opt] tag t The tag.
 function tag.getnmaster(t)
     gdebug.deprecate("Use t.master_count instead of awful.tag.setnmaster", {deprecated_in=4})
 
@@ -1335,9 +1388,10 @@ end
 -- @staticfct awful.tag.incnmaster
 -- @see master_count
 -- @tparam number add Value to add to number of master windows.
--- @tparam[opt] tag t The tag to modify, if null tag.selected() is used.
+-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify.
 -- @tparam[opt=false] boolean sensible Limit nmaster based on the number of
 --   visible tiled windows?
+-- @noreturn
 function tag.incnmaster(add, t, sensible)
     t = t or ascreen.focused().selected_tag
 
@@ -1365,7 +1419,7 @@ end
 -- @DOC_wibox_awidget_taglist_icon_EXAMPLE@
 --
 -- @property icon
--- @tparam path|surface icon The icon
+-- @tparam[opt=nil] image|nil icon
 -- @propemits false false
 -- @see awful.widget.taglist
 -- @see gears.surface
@@ -1374,9 +1428,9 @@ end
 
 --- Set the tag icon
 -- @deprecated awful.tag.seticon
+-- @tparam gears.surface|string icon The icon to set, either path or image object
+-- @tparam tag tag The tag
 -- @see icon
--- @param icon the icon to set, either path or image object
--- @tparam tag tag the tag
 function tag.seticon(icon, _tag)
     gdebug.deprecate("Use t.icon = icon instead of awful.tag.seticon", {deprecated_in=4})
 
@@ -1387,7 +1441,7 @@ end
 --- Get the tag icon
 -- @deprecated awful.tag.geticon
 -- @see icon
--- @tparam tag tag the tag
+-- @tparam tag tag The tag
 function tag.geticon(_tag)
     gdebug.deprecate("Use t.icon instead of awful.tag.geticon", {deprecated_in=4})
 
@@ -1398,7 +1452,7 @@ end
 --- The default number of columns.
 --
 -- @beautiful beautiful.column_count
--- @param integer (default: 1)
+-- @tparam[opt=1] integer column_count
 -- @see column_count
 
 --- Set the number of columns.
@@ -1406,7 +1460,8 @@ end
 -- @DOC_sequences_tag_column_count_EXAMPLE@
 --
 -- @property column_count
--- @tparam integer ncol Has to be greater than 1
+-- @tparam[opt=beautiful.column_count or 1] integer column_count Has to be greater than 1
+-- @rangestart 1
 -- @emits property::ncol Deprecated.
 -- @emits property::column_count When the value changes.
 -- @see awful.tag.incncol
@@ -1427,8 +1482,8 @@ end
 --- Set number of column windows.
 -- @deprecated awful.tag.setncol
 -- @see column_count
--- @param ncol The number of column.
--- @param t The tag to modify, if null tag.selected() is used.
+-- @tparam integer ncol The number of column.
+-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify.
 function tag.setncol(ncol, t)
     gdebug.deprecate("Use t.column_count = new_index instead of awful.tag.setncol", {deprecated_in=4})
 
@@ -1442,7 +1497,7 @@ end
 --- Get number of column windows.
 -- @deprecated awful.tag.getncol
 -- @see column_count
--- @param[opt] t The tag.
+-- @tparam[opt] tag t The tag.
 function tag.getncol(t)
     gdebug.deprecate("Use t.column_count instead of awful.tag.getncol", {deprecated_in=4})
 
@@ -1453,9 +1508,10 @@ end
 --- Increase number of column windows.
 -- @staticfct awful.tag.incncol
 -- @tparam number add Value to add to number of column windows.
--- @tparam[opt] tag t The tag to modify, if null tag.selected() is used.
+-- @tparam[opt=awful.screen.focused().selected_tag] tag t The tag to modify.
 -- @tparam[opt=false] boolean sensible Limit column_count based on the number
 --   of visible tiled windows?
+-- @noreturn
 function tag.incncol(add, t, sensible)
     t = t or ascreen.focused().selected_tag
 
@@ -1487,6 +1543,7 @@ end
 --
 -- @staticfct awful.tag.viewnone
 -- @tparam[opt] int|screen screen The screen.
+-- @noreturn
 function tag.viewnone(screen)
     screen = screen or ascreen.focused()
     local tags = screen.tags
@@ -1506,6 +1563,7 @@ end
 -- @see screen.tags
 -- @tparam number i The **relative** index to see.
 -- @tparam[opt] screen screen The screen.
+-- @noreturn
 -- @see awful.tag.viewnext
 -- @see awful.tag.viewprev
 function tag.viewidx(i, screen)
@@ -1530,8 +1588,8 @@ end
 --- Get a tag's index in the gettags() table.
 -- @deprecated awful.tag.getidx
 -- @see index
--- @param query_tag The tag object to find. [selected()]
--- @return The index of the tag, nil if the tag is not found.
+-- @tparam tag query_tag The tag object to find. [selected()]
+-- @treturn integer|nil The index of the tag, nil if the tag is not found.
 function tag.getidx(query_tag)
     gdebug.deprecate("Use t.index instead of awful.tag.getidx", {deprecated_in=4})
 
@@ -1547,10 +1605,11 @@ end
 --
 -- @staticfct awful.tag.viewnext
 -- @tparam screen screen The screen.
+-- @noreturn
 -- @see awful.tag.viewidx
 -- @see awful.tag.viewprev
 function tag.viewnext(screen)
-    return tag.viewidx(1, screen)
+    tag.viewidx(1, screen)
 end
 
 --- View previous tag. This is the same a `tag.viewidx(-1)`.
@@ -1561,10 +1620,11 @@ end
 --
 -- @staticfct awful.tag.viewprev
 -- @tparam screen screen The screen.
+-- @noreturn
 -- @see awful.tag.viewidx
 -- @see awful.tag.viewnext
 function tag.viewprev(screen)
-    return tag.viewidx(-1, screen)
+    tag.viewidx(-1, screen)
 end
 
 --- View only a tag.
@@ -1572,6 +1632,7 @@ end
 -- @DOC_sequences_tag_view_only_EXAMPLE@
 --
 -- @method view_only
+-- @noreturn
 -- @see selected
 function tag.object.view_only(self)
     local tags = self.screen.tags
@@ -1590,6 +1651,7 @@ end
 
 --- View only a tag.
 -- @deprecated awful.tag.viewonly
+-- @noreturn
 -- @see tag.view_only
 -- @tparam tag t The tag object.
 function tag.viewonly(t)
@@ -1608,6 +1670,7 @@ end
 -- @tparam table tags A table with tags to view only.
 -- @tparam[opt] screen screen The screen of the tags.
 -- @tparam[opt=#tags] number maximum The maximum number of tags to select.
+-- @noreturn
 function tag.viewmore(tags, screen, maximum)
     maximum = maximum or #tags
     local selected = 0
@@ -1638,8 +1701,9 @@ end
 
 --- Toggle selection of a tag
 -- @staticfct awful.tag.viewtoggle
--- @see selected
 -- @tparam tag t Tag to be toggled
+-- @noreturn
+-- @see selected
 function tag.viewtoggle(t)
     t.selected = not t.selected
     capi.screen[tag.getproperty(t, "screen")]:emit_signal("tag::history::update")
@@ -1651,7 +1715,7 @@ end
 --
 -- @deprecated awful.tag.getdata
 -- @tparam tag t The tag.
--- @return The data table.
+-- @treturn table The data table.
 function tag.getdata(t)
     return t._private.awful_tag_properties
 end
@@ -1679,8 +1743,8 @@ end
 -- Use `t.prop = value`
 --
 -- @deprecated awful.tag.setproperty
--- @param t The tag.
--- @param prop The property name.
+-- @tparam tag t The tag.
+-- @tparam string prop The property name.
 -- @param value The value.
 function tag.setproperty(t, prop, value)
     if not t._private.awful_tag_properties then
@@ -1695,7 +1759,8 @@ end
 
 --- Tag a client with the set of current tags.
 -- @deprecated awful.tag.withcurrent
--- @param c The client to tag.
+-- @tparam client c The client to tag.
+-- @noreturn
 function tag.withcurrent(c)
     gdebug.deprecate("Use c:to_selected_tags() instead of awful.tag.selectedlist", {deprecated_in=4})
 
@@ -1732,9 +1797,10 @@ end
 -- future. When a tag is detached from the screen, its signal is removed.
 --
 -- @staticfct awful.tag.attached_connect_signal
--- @tparam screen screen The screen concerned, or all if nil.
--- @tparam[opt] string signal The signal name.
--- @tparam[opt] function Callback
+-- @tparam screen|nil screen The screen concerned, or all if `nil`.
+-- @tparam string signal The signal name.
+-- @tparam function callback
+-- @noreturn
 function tag.attached_connect_signal(screen, ...)
     if screen then
         attached_connect_signal_screen(screen, ...)
@@ -1809,12 +1875,12 @@ capi.tag.connect_signal("request::select", tag.object.view_only)
 
 --- Emitted when the number of urgent clients on this tag changes.
 -- @signal property::urgent
--- @param boolean `true` if there is at least one urgent client on the tag.
+-- @tparam boolean urgent `true` if there is at least one urgent client on the tag.
 -- @see client.urgent
 
 --- Emitted when the number of urgent clients on this tag changes.
 -- @signal property::urgent_count
--- @param integer The number of urgent clients on the tag.
+-- @tparam integer count The number of urgent clients on the tag.
 -- @see client.urgent
 
 --- Emitted when a screen is removed.

lib/awful/titlebar.lua

@@ -1,6 +1,8 @@
 ---------------------------------------------------------------------------
---- Titlebars for awful.
---**Create a titlebar:**
+--- Create widget area on the edge of a client.
+--
+-- Create a titlebar
+-- =================
 --
 -- This example reproduces what the default `rc.lua` does. It shows how to
 -- handle the titlebars on a lower level.
@@ -39,418 +41,501 @@ local titlebar = {
 
 
 --- Show tooltips when hover on titlebar buttons.
+--
 -- @tfield[opt=true] boolean awful.titlebar.enable_tooltip
 -- @param boolean
 
 --- Title to display if client name is not set.
+--
 -- @field[opt='\<unknown\>'] awful.titlebar.fallback_name
 -- @tparam[opt='\<unknown\>'] string fallback_name
 
-
 --- The titlebar foreground (text) color.
+--
 -- @beautiful beautiful.titlebar_fg_normal
 -- @param color
 -- @see gears.color
 
 --- The titlebar background color.
+--
 -- @beautiful beautiful.titlebar_bg_normal
 -- @param color
 -- @see gears.color
 
 --- The titlebar background image image.
+--
 -- @beautiful beautiful.titlebar_bgimage_normal
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- The titlebar foreground (text) color.
+--
 -- @beautiful beautiful.titlebar_fg
 -- @param color
 -- @see gears.color
 
 --- The titlebar background color.
+--
 -- @beautiful beautiful.titlebar_bg
 -- @param color
 -- @see gears.color
 
 --- The titlebar background image image.
+--
 -- @beautiful beautiful.titlebar_bgimage
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- The focused titlebar foreground (text) color.
+--
 -- @beautiful beautiful.titlebar_fg_focus
 -- @param color
 -- @see gears.color
 
 --- The focused titlebar background color.
+--
 -- @beautiful beautiful.titlebar_bg_focus
 -- @param color
 -- @see gears.color
 
 --- The focused titlebar background image image.
+--
 -- @beautiful beautiful.titlebar_bgimage_focus
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- The urgent titlebar foreground (text) color.
+--
 -- @beautiful beautiful.titlebar_fg_urgent
 -- @param color
 -- @see gears.color
 
 --- The urgent titlebar background color.
+--
 -- @beautiful beautiful.titlebar_bg_urgent
 -- @param color
 -- @see gears.color
 
---- The urgent titlebar background image image.
+--- The urgent titlebar background image.
+--
 -- @beautiful beautiful.titlebar_bgimage_urgent
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_normal.
+--- The normal non-floating button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_normal
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_normal.
+--- The normal non-maximized button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_normal
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- minimize_button_normal.
+--- The normal minimize button image.
+--
 -- @beautiful beautiful.titlebar_minimize_button_normal
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- minimize_button_normal_hover.
+--- The hovered minimize button image.
+--
 -- @beautiful beautiful.titlebar_minimize_button_normal_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- minimize_button_normal_press.
+--- The pressed minimize button image.
+--
 -- @beautiful beautiful.titlebar_minimize_button_normal_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- close_button_normal.
+--- The normal close button image.
+--
 -- @beautiful beautiful.titlebar_close_button_normal
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- close_button_normal_hover.
+--- The hovered close button image.
+--
 -- @beautiful beautiful.titlebar_close_button_normal_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- close_button_normal_press.
+--- The pressed close button image.
+--
 -- @beautiful beautiful.titlebar_close_button_normal_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_normal.
+--- The normal non-ontop button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_normal
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_normal.
+--- The normal non-sticky button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_normal
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_focus.
+--- The focused client non-floating button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_focus
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_focus.
+--- The focused client non-maximized button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_focus
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- minimize_button_focus.
+--- The focused client minimize button image.
+--
 -- @beautiful beautiful.titlebar_minimize_button_focus
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- minimize_button_focus_hover.
+--- The hovered+focused client minimize button image.
+--
 -- @beautiful beautiful.titlebar_minimize_button_focus_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- minimize_button_focus_press.
+--- The pressed+focused minimize button image.
+--
 -- @beautiful beautiful.titlebar_minimize_button_focus_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- close_button_focus.
+--- The focused client close button image.
+--
 -- @beautiful beautiful.titlebar_close_button_focus
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- close_button_focus_hover.
+--- The hovered+focused close button image.
+--
 -- @beautiful beautiful.titlebar_close_button_focus_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- close_button_focus_press.
+--- The pressed+focused close button image.
+--
 -- @beautiful beautiful.titlebar_close_button_focus_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_focus.
+--- The focused client non-ontop button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_focus
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_focus.
+--- The focused client sticky button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_focus
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_normal_active.
+--- The normal floating button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_normal_active
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_normal_active_hover.
+--- The hovered floating client button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_normal_active_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_normal_active_press.
+--- The pressed floating client button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_normal_active_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_normal_active.
+--- The maximized client button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_normal_active
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_normal_active_hover.
+--- The hozered+maximized client button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_normal_active_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_normal_active_press.
+--- The pressed+maximized button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_normal_active_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_normal_active.
+--- The ontop button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_normal_active
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_normal_active_hover.
+--- The hovered+ontop client button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_normal_active_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_normal_active_press.
+--- The pressed+ontop client button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_normal_active_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_normal_active.
+--- The sticky button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_normal_active
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_normal_active_hover.
+--- The hovered+sticky button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_normal_active_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_normal_active_press.
+--- The pressed+sticky client button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_normal_active_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_focus_active.
+--- The floating+focused client button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_focus_active
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_focus_active_hover.
+--- The hovered+floating+focused button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_focus_active_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_focus_active_press.
+--- The pressed+floating+focused button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_focus_active_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_focus_active.
+--- The maximized+focused button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_focus_active
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_focus_active_hover.
+--- The hovered+maximized+focused button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_focus_active_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_focus_active_press.
+--- The pressed+maximized+focused button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_focus_active_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_focus_active.
+--- The ontop+focused button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_focus_active
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_focus_active_hover.
+--- The hovered+ontop+focused button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_focus_active_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_focus_active_press.
+--- The pressed+ontop+focused button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_focus_active_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_focus_active.
+--- The sticky+focused button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_focus_active
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_focus_active_hover.
+--- The hovered+sticky+focused button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_focus_active_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_focus_active_press.
+--- The pressed+sticky+focused button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_focus_active_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_normal_inactive.
+--- The inactive+floating button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_normal_inactive
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_normal_inactive_hover.
+--- The hovered+inactive+floating button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_normal_inactive_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_normal_inactive_press.
+--- The pressed+inactive+floating button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_normal_inactive_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_normal_inactive.
+--- The inactive+maximized button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_normal_inactive
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_normal_inactive_hover.
+--- The hovered+inactive+maximized button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_normal_inactive_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_normal_inactive_press.
+--- The pressed+maximized+inactive button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_normal_inactive_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_normal_inactive.
+--- The inactive+ontop button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_normal_inactive
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_normal_inactive_hover.
+--- The hovered+inactive+ontop button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_normal_inactive_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_normal_inactive_press.
+--- The pressed+inactive+ontop button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_normal_inactive_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_normal_inactive.
+--- The inactive+sticky button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_normal_inactive
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_normal_inactive_hover.
+--- The hovered+inactive+sticky button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_normal_inactive_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_normal_inactive_press.
+--- The pressed+inactive+sticky button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_normal_inactive_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_focus_inactive.
+--- The inactive+focused+floating button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_focus_inactive
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_focus_inactive_hover.
+--- The hovered+inactive+focused+floating button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_focus_inactive_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- floating_button_focus_inactive_press.
+--- The pressed+inactive+focused+floating button image.
+--
 -- @beautiful beautiful.titlebar_floating_button_focus_inactive_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_focus_inactive.
+--- The inactive+focused+maximized button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_focus_inactive
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_focus_inactive_hover.
+--- The hovered+inactive+focused+maximized button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_focus_inactive_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- maximized_button_focus_inactive_press.
+--- The pressed+inactive+focused+maximized button image.
+--
 -- @beautiful beautiful.titlebar_maximized_button_focus_inactive_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_focus_inactive.
+--- The inactive+focused+ontop button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_focus_inactive
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_focus_inactive_hover.
+--- The hovered+inactive+focused+ontop button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_focus_inactive_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- ontop_button_focus_inactive_press.
+--- The pressed+inactive+focused+ontop button image.
+--
 -- @beautiful beautiful.titlebar_ontop_button_focus_inactive_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_focus_inactive.
+--- The inactive+focused+sticky button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_focus_inactive
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_focus_inactive_hover.
+--- The hovered+inactive+focused+sticky button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_focus_inactive_hover
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
---- sticky_button_focus_inactive_press.
+--- The pressed+inactive+focused+sticky button image.
+--
 -- @beautiful beautiful.titlebar_sticky_button_focus_inactive_press
 -- @tparam gears.surface|string path
 -- @see gears.surface
 
 --- Set a declarative widget hierarchy description.
+--
 -- See [The declarative layout system](../documentation/03-declarative-layout.md.html)
--- @param args An array containing the widgets disposition
+-- @tparam table args An array containing the widgets disposition
 -- @method setup
+-- @noreturn
 
 
 local all_titlebars = setmetatable({}, { __mode = 'k' })
@@ -552,6 +637,18 @@ end
 -- @tparam[opt] string args.font
 -- @constructorfct awful.titlebar
 -- @treturn wibox.drawable The newly created titlebar object.
+-- @usebeautiful beautiful.titlebar_fg_normal
+-- @usebeautiful beautiful.titlebar_bg_normal
+-- @usebeautiful beautiful.titlebar_bgimage_normal
+-- @usebeautiful beautiful.titlebar_fg
+-- @usebeautiful beautiful.titlebar_bg
+-- @usebeautiful beautiful.titlebar_bgimage
+-- @usebeautiful beautiful.titlebar_fg_focus
+-- @usebeautiful beautiful.titlebar_bg_focus
+-- @usebeautiful beautiful.titlebar_bgimage_focus
+-- @usebeautiful beautiful.titlebar_fg_urgent
+-- @usebeautiful beautiful.titlebar_bg_urgent
+-- @usebeautiful beautiful.titlebar_bgimage_urgent
 local function new(c, args)
     args = args or {}
     local position = args.position or "top"
@@ -614,9 +711,10 @@ local function new(c, args)
 end
 
 --- Show the client's titlebar.
--- @param c The client whose titlebar is modified
+-- @tparam client c The client whose titlebar is modified
 -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`,
 --   `"right"`, `"top"`, `"bottom"`.
+-- @noreturn
 -- @staticfct awful.titlebar.show
 -- @request client titlebars show granted Called when `awful.titlebar.show` is
 --  called.
@@ -630,9 +728,10 @@ function titlebar.show(c, position)
 end
 
 --- Hide the client's titlebar.
--- @param c The client whose titlebar is modified
+-- @tparam client c The client whose titlebar is modified
 -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`,
 --   `"right"`, `"top"`, `"bottom"`.
+-- @noreturn
 -- @staticfct awful.titlebar.hide
 function titlebar.hide(c, position)
     position = position or "top"
@@ -640,9 +739,10 @@ function titlebar.hide(c, position)
 end
 
 --- Toggle the client's titlebar, hiding it if it is visible, otherwise showing it.
--- @param c The client whose titlebar is modified
+-- @tparam client c The client whose titlebar is modified
 -- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`,
 --   `"right"`, `"top"`, `"bottom"`.
+-- @noreturn
 -- @staticfct awful.titlebar.toggle
 -- @request client titlebars toggle granted Called when `awful.titlebar.toggle` is
 --  called.
@@ -704,7 +804,7 @@ end
 -- Please note that this returns a textbox and all of textbox' API is available.
 -- This way, you can e.g. modify the font that is used.
 --
--- @param c The client for which a titlewidget should be created.
+-- @tparam client c The client for which a titlewidget should be created.
 -- @return The title widget.
 -- @constructorfct awful.titlebar.widget.titlewidget
 function titlebar.widget.titlewidget(c)
@@ -728,7 +828,7 @@ end
 -- Please note that this returns an imagebox and all of the imagebox' API is
 -- available. This way, you can e.g. disallow resizes.
 --
--- @param c The client for which an icon widget should be created.
+-- @tparam client c The client for which an icon widget should be created.
 -- @return The icon widget.
 -- @constructorfct awful.titlebar.widget.iconwidget
 function titlebar.widget.iconwidget(c)
@@ -745,12 +845,12 @@ end
 -- then found in the theme as `titlebar_[name]_button_[normal/focus]_[state]`.
 -- If that value does not exist, the focused state is ignored for the next try.
 --
--- @param c The client for which a button is created.
+-- @tparam client c The client for which a button is created.
 -- @tparam string name Name of the button, used for accessing the theme and
 --   in the tooltip.
--- @param selector A function that selects the image that should be displayed.
--- @param action Function that is called when the button is clicked.
--- @return The widget
+-- @tparam function selector A function that selects the image that should be displayed.
+-- @tparam function action Function that is called when the button is clicked.
+-- @treturn wibox.widget The widget
 -- @constructorfct awful.titlebar.widget.button
 function titlebar.widget.button(c, name, selector, action)
     local ret = imagebox()
@@ -838,8 +938,23 @@ function titlebar.widget.button(c, name, selector, action)
 end
 
 --- Create a new float button for a client.
--- @param c The client for which the button is wanted.
+--
 -- @constructorfct awful.titlebar.widget.floatingbutton
+-- @tparam client c The client for which the button is wanted.
+-- @usebeautiful beautiful.titlebar_floating_button_normal
+-- @usebeautiful beautiful.titlebar_floating_button_focus
+-- @usebeautiful beautiful.titlebar_floating_button_normal_active
+-- @usebeautiful beautiful.titlebar_floating_button_normal_active_hover
+-- @usebeautiful beautiful.titlebar_floating_button_normal_active_press
+-- @usebeautiful beautiful.titlebar_floating_button_focus_active
+-- @usebeautiful beautiful.titlebar_floating_button_focus_active_hover
+-- @usebeautiful beautiful.titlebar_floating_button_focus_active_press
+-- @usebeautiful beautiful.titlebar_floating_button_normal_inactive
+-- @usebeautiful beautiful.titlebar_floating_button_normal_inactive_hover
+-- @usebeautiful beautiful.titlebar_floating_button_normal_inactive_press
+-- @usebeautiful beautiful.titlebar_floating_button_focus_inactive
+-- @usebeautiful beautiful.titlebar_floating_button_focus_inactive_hover
+-- @usebeautiful beautiful.titlebar_floating_button_focus_inactive_press
 function titlebar.widget.floatingbutton(c)
     local widget = titlebar.widget.button(c, "floating", aclient.object.get_floating, aclient.floating.toggle)
     update_on_signal(c, "property::floating", widget)
@@ -847,8 +962,23 @@ function titlebar.widget.floatingbutton(c)
 end
 
 --- Create a new maximize button for a client.
--- @param c The client for which the button is wanted.
+--
 -- @constructorfct awful.titlebar.widget.maximizedbutton
+-- @tparam client c The client for which the button is wanted.
+-- @usebeautiful beautiful.titlebar_maximized_button_focus_active
+-- @usebeautiful beautiful.titlebar_maximized_button_focus_active_hover
+-- @usebeautiful beautiful.titlebar_maximized_button_focus_active_press
+-- @usebeautiful beautiful.titlebar_maximized_button_normal_inactive
+-- @usebeautiful beautiful.titlebar_maximized_button_normal_inactive_hover
+-- @usebeautiful beautiful.titlebar_maximized_button_normal_inactive_press
+-- @usebeautiful beautiful.titlebar_maximized_button_focus_inactive
+-- @usebeautiful beautiful.titlebar_maximized_button_focus_inactive_hover
+-- @usebeautiful beautiful.titlebar_maximized_button_focus_inactive_press
+-- @usebeautiful beautiful.titlebar_maximized_button_normal
+-- @usebeautiful beautiful.titlebar_maximized_button_focus
+-- @usebeautiful beautiful.titlebar_maximized_button_normal_active
+-- @usebeautiful beautiful.titlebar_maximized_button_normal_active_hover
+-- @usebeautiful beautiful.titlebar_maximized_button_normal_active_press
 function titlebar.widget.maximizedbutton(c)
     local widget = titlebar.widget.button(c, "maximized", function(cl)
         return cl.maximized
@@ -860,8 +990,15 @@ function titlebar.widget.maximizedbutton(c)
 end
 
 --- Create a new minimize button for a client.
--- @param c The client for which the button is wanted.
+--
 -- @constructorfct awful.titlebar.widget.minimizebutton
+-- @tparam client c The client for which the button is wanted.
+-- @usebeautiful beautiful.titlebar_minimize_button_normal
+-- @usebeautiful beautiful.titlebar_minimize_button_normal_hover
+-- @usebeautiful beautiful.titlebar_minimize_button_normal_press
+-- @usebeautiful beautiful.titlebar_minimize_button_focus
+-- @usebeautiful beautiful.titlebar_minimize_button_focus_hover
+-- @usebeautiful beautiful.titlebar_minimize_button_focus_press
 function titlebar.widget.minimizebutton(c)
     local widget = titlebar.widget.button(c, "minimize",
                                           function() return "" end,
@@ -871,15 +1008,37 @@ function titlebar.widget.minimizebutton(c)
 end
 
 --- Create a new closing button for a client.
--- @param c The client for which the button is wanted.
+--
 -- @constructorfct awful.titlebar.widget.closebutton
+-- @tparam client c The client for which the button is wanted.
+-- @usebeautiful beautiful.titlebar_close_button_normal
+-- @usebeautiful beautiful.titlebar_close_button_normal_hover
+-- @usebeautiful beautiful.titlebar_close_button_normal_press
+-- @usebeautiful beautiful.titlebar_close_button_focus
+-- @usebeautiful beautiful.titlebar_close_button_focus_hover
+-- @usebeautiful beautiful.titlebar_close_button_focus_press
 function titlebar.widget.closebutton(c)
     return titlebar.widget.button(c, "close", function() return "" end, function(cl) cl:kill() end)
 end
 
 --- Create a new ontop button for a client.
--- @param c The client for which the button is wanted.
+--
 -- @constructorfct awful.titlebar.widget.ontopbutton
+-- @tparam client c The client for which the button is wanted.
+-- @usebeautiful beautiful.titlebar_ontop_button_normal
+-- @usebeautiful beautiful.titlebar_ontop_button_focus
+-- @usebeautiful beautiful.titlebar_ontop_button_normal_active
+-- @usebeautiful beautiful.titlebar_ontop_button_normal_active_hover
+-- @usebeautiful beautiful.titlebar_ontop_button_normal_active_press
+-- @usebeautiful beautiful.titlebar_ontop_button_focus_active
+-- @usebeautiful beautiful.titlebar_ontop_button_focus_active_hover
+-- @usebeautiful beautiful.titlebar_ontop_button_focus_active_press
+-- @usebeautiful beautiful.titlebar_ontop_button_normal_inactive
+-- @usebeautiful beautiful.titlebar_ontop_button_normal_inactive_hover
+-- @usebeautiful beautiful.titlebar_ontop_button_normal_inactive_press
+-- @usebeautiful beautiful.titlebar_ontop_button_focus_inactive
+-- @usebeautiful beautiful.titlebar_ontop_button_focus_inactive_hover
+-- @usebeautiful beautiful.titlebar_ontop_button_focus_inactive_press
 function titlebar.widget.ontopbutton(c)
     local widget = titlebar.widget.button(c, "ontop",
                                           function(cl) return cl.ontop end,
@@ -889,8 +1048,22 @@ function titlebar.widget.ontopbutton(c)
 end
 
 --- Create a new sticky button for a client.
--- @param c The client for which the button is wanted.
 -- @constructorfct awful.titlebar.widget.stickybutton
+-- @tparam client c The client for which the button is wanted.
+-- @usebeautiful beautiful.titlebar_sticky_button_normal
+-- @usebeautiful beautiful.titlebar_sticky_button_focus
+-- @usebeautiful beautiful.titlebar_sticky_button_normal_active
+-- @usebeautiful beautiful.titlebar_sticky_button_normal_active_hover
+-- @usebeautiful beautiful.titlebar_sticky_button_normal_active_press
+-- @usebeautiful beautiful.titlebar_sticky_button_focus_active
+-- @usebeautiful beautiful.titlebar_sticky_button_focus_active_hover
+-- @usebeautiful beautiful.titlebar_sticky_button_focus_active_press
+-- @usebeautiful beautiful.titlebar_sticky_button_normal_inactive
+-- @usebeautiful beautiful.titlebar_sticky_button_normal_inactive_hover
+-- @usebeautiful beautiful.titlebar_sticky_button_normal_inactive_press
+-- @usebeautiful beautiful.titlebar_sticky_button_focus_inactive
+-- @usebeautiful beautiful.titlebar_sticky_button_focus_inactive_hover
+-- @usebeautiful beautiful.titlebar_sticky_button_focus_inactive_press
 function titlebar.widget.stickybutton(c)
     local widget = titlebar.widget.button(c, "sticky",
                                           function(cl) return cl.sticky end,

lib/awful/tooltip.lua

@@ -107,7 +107,7 @@ local offset = {
 
 --- The tooltip opacity.
 -- @beautiful beautiful.tooltip_opacity
--- @param number opacity Between 0 and 1
+-- @tparam number opacity Between 0 and 1
 
 --- The tooltip margins.
 -- @beautiful beautiful.tooltip_gaps
@@ -206,7 +206,8 @@ end
 
 --- The wibox containing the tooltip widgets.
 -- @property wibox
--- @param wibox
+-- @tparam wibox wibox
+-- @propertydefault Autogenerated.
 
 function tooltip:get_wibox()
     if self._private.wibox then
@@ -229,7 +230,7 @@ end
 
 --- Is the tooltip visible?
 -- @property visible
--- @param boolean
+-- @tparam[opt=true] boolean visible
 -- @propemits true false
 
 function tooltip:get_visible()
@@ -257,27 +258,24 @@ end
 --
 -- @DOC_awful_tooltip_align2_EXAMPLE@
 --
--- The following values are valid:
---
--- * top_left
--- * left
--- * bottom_left
--- * right
--- * top_right
--- * bottom_right
--- * bottom
--- * top
---
 -- @property align
--- @param string
--- @see mode
--- @see preferred_positions
+-- @tparam[opt="right"] string|nil align
+-- @propertyvalue "top_left"
+-- @propertyvalue "left"
+-- @propertyvalue "bottom_left"
+-- @propertyvalue "right"
+-- @propertyvalue "top_right"
+-- @propertyvalue "bottom_right"
+-- @propertyvalue "bottom"
+-- @propertyvalue "top"
 -- @propemits true false
 -- @propbeautiful
+-- @see mode
+-- @see preferred_positions
 
 --- The default tooltip alignment.
 -- @beautiful beautiful.tooltip_align
--- @param string
+-- @tparam string tooltip_align
 -- @see align
 
 function tooltip:get_align()
@@ -300,7 +298,7 @@ end
 -- @DOC_awful_tooltip_shape_EXAMPLE@
 --
 -- @property shape
--- @tparam gears.shape shape
+-- @tparam[opt=gears.shape.rectangle] shap|nil shape
 -- @see gears.shape
 -- @propemits true false
 -- @propbeautiful
@@ -324,13 +322,10 @@ end
 --
 -- @DOC_awful_tooltip_mode2_EXAMPLE@
 --
--- Valid modes are:
---
--- * "mouse": Next to the mouse cursor
--- * "outside": Outside of the widget
---
 -- @property mode
--- @param string
+-- @tparam[opt="mouse"] string mode
+-- @propertyvalue "mouse" Next to the mouse cursor.
+-- @propertyvalue "outside" Outside of the widget.
 -- @propemits true false
 
 function tooltip:set_mode(mode)
@@ -358,12 +353,10 @@ end
 -- * "left"
 -- * "bottom"
 --
--- The default is:
---
---    {"top", "right", "left", "bottom"}
---
 -- @property preferred_positions
 -- @tparam table preferred_positions The position, ordered by priorities
+-- @propertydefault `{"top", "right", "left", "bottom"}`
+-- @tablerowtype A list of strings.
 -- @propemits true false
 -- @see align
 -- @see mode
@@ -401,16 +394,14 @@ end
 --
 -- The valid table values are:
 --
--- * front
--- * middle
--- * back
---
--- The default is:
---
---    {"front", "back", "middle"}
+-- * "front"
+-- * "middle"
+-- * "back"
 --
 -- @property preferred_alignments
--- @param string
+-- @tparam table preferred_alignments
+-- @tablerowtype A list of strings.
+-- @propertydefault `{"front", "back", "middle"}`
 -- @propemits true false
 -- @see preferred_positions
 
@@ -430,7 +421,7 @@ end
 --- Change displayed text.
 --
 -- @property text
--- @tparam string  text New tooltip text, passed to
+-- @tparam[opt=""] string text New tooltip text, passed to
 --   `wibox.widget.textbox.set_text`.
 -- @propemits true false
 -- @see wibox.widget.textbox
@@ -447,7 +438,7 @@ end
 --- Change displayed markup.
 --
 -- @property markup
--- @tparam string  text New tooltip markup, passed to
+-- @tparam[opt=""] string markup New tooltip markup, passed to
 --   `wibox.widget.textbox.set_markup`.
 -- @propemits true false
 -- @see wibox.widget.textbox
@@ -464,7 +455,9 @@ end
 --- Change the tooltip's update interval.
 --
 -- @property timeout
--- @tparam number timeout The timeout value.
+-- @tparam[opt=1] number timeout
+-- @negativeallowed false
+-- @propertyunit second
 -- @propemits true false
 
 function tooltip:set_timeout(timeout)
@@ -479,7 +472,15 @@ end
 -- @DOC_awful_tooltip_margins_EXAMPLE@
 --
 -- @property margins
--- @tparam number|table New margins value.
+-- @tparam[opt=0] number|table margins
+-- @tparam[opt=0] number margins.top
+-- @tparam[opt=0] number margins.bottom
+-- @tparam[opt=0] number margins.left
+-- @tparam[opt=0] number margins.right
+-- @negativeallowed true
+-- @propertyunit pixel
+-- @propertytype number A single value for each sides.
+-- @propertytype table A different value for each side.
 -- @propemits true false
 
 function tooltip:set_margins(val)
@@ -492,7 +493,9 @@ end
 -- @DOC_awful_tooltip_border_width_EXAMPLE@
 --
 -- @property border_width
--- @param number
+-- @tparam[opt=0] number|nil border_width
+-- @negativeallowed false
+-- @propertyunit pixel
 -- @propemits true false
 -- @propbeautiful
 
@@ -506,8 +509,10 @@ end
 -- @DOC_awful_tooltip_border_color_EXAMPLE@
 --
 -- @property border_color
--- @param color
+-- @tparam[opt=beautiful.tooltip_border_color or beautiful.border_color_normal or beautiful.fg_normal]
+--  color|nil border_color
 -- @propemits true false
+-- @propbeautiful
 
 function tooltip:set_border_color(val)
     self.widget.border_color = val
@@ -519,8 +524,12 @@ end
 -- @DOC_awful_tooltip_margins_leftright_EXAMPLE@
 --
 -- @property margins_leftright
--- @tparam number New margins value.
+-- @tparam[opt=0] number margins_leftright
+-- @negativeallowed true
+-- @propertyunit pixel
 -- @propemits true false
+-- @see margins
+-- @see margins_topbottom
 
 function tooltip:set_margin_leftright(val)
     self.marginbox:set_left(val)
@@ -538,8 +547,12 @@ end
 -- @DOC_awful_tooltip_margins_topbottom_EXAMPLE@
 --
 -- @property margins_topbottom
--- @tparam number New margins value.
+-- @tparam[opt=0] number margins_topbottom
+-- @negativeallowed true
+-- @propertyunit pixel
 -- @propemits true false
+-- @see margins
+-- @see margins_leftright
 
 function tooltip:set_margin_topbottom(val)
     self.marginbox:set_top(val)
@@ -557,8 +570,17 @@ end
 -- @DOC_awful_tooltip_gaps_EXAMPLE@
 --
 -- @property gaps
--- @tparam number|table New margins value.
+-- @tparam[opt=0] number|table|nil gaps
+-- @tparam[opt=0] number gaps.top
+-- @tparam[opt=0] number gaps.bottom
+-- @tparam[opt=0] number gaps.left
+-- @tparam[opt=0] number gaps.right
+-- @negativeallowed true
+-- @propertytype number A single value for each sides.
+-- @propertytype table A different value for each side.
+-- @propertyunit pixel
 -- @propemits true false
+-- @propbeautiful
 
 function tooltip:set_gaps(val)
     self._private.gaps = val
@@ -570,9 +592,9 @@ end
 
 --- Add tooltip to an object.
 --
--- @tparam tooltip self The tooltip.
 -- @tparam gears.object obj An object with `mouse::enter` and
 --   `mouse::leave` signals.
+-- @noreturn
 -- @method add_to_object
 function tooltip:add_to_object(obj)
     if not obj then return end
@@ -583,9 +605,9 @@ end
 
 --- Remove tooltip from an object.
 --
--- @tparam tooltip self The tooltip.
 -- @tparam gears.object obj An object with `mouse::enter` and
 --   `mouse::leave` signals.
+-- @noreturn
 -- @method remove_from_object
 function tooltip:remove_from_object(obj)
     obj:disconnect_signal("mouse::enter", self.show)
@@ -617,14 +639,14 @@ end
 -- @tparam[opt=apply_dpi(5)] integer args.margin_leftright The left/right margin for the text.
 -- @tparam[opt=apply_dpi(3)] integer args.margin_topbottom The top/bottom margin for the text.
 -- @tparam[opt=nil] gears.shape args.shape The shape.
--- @tparam[opt] string args.bg The background color.
--- @tparam[opt] string args.fg The foreground color.
--- @tparam[opt] string args.border_color The tooltip border color.
--- @tparam[opt] number args.border_width The tooltip border width.
+-- @tparam[opt=beautiful.tooltip_bg] string args.bg The background color.
+-- @tparam[opt=beautiful.tooltip_fg] string args.fg The foreground color.
+-- @tparam[opt=beautiful.tooltip_border_color] string args.border_color The tooltip border color.
+-- @tparam[opt=beautiful.tooltip_border_width] number args.border_width The tooltip border width.
 -- @tparam[opt] string args.align The horizontal alignment.
--- @tparam[opt] string args.font The tooltip font.
--- @tparam[opt] number args.opacity The tooltip opacity.
--- @tparam[opt] table|number args.gaps The tooltip margins.
+-- @tparam[opt=beautiful.tooltip_font] string args.font The tooltip font.
+-- @tparam[opt=beautiful.tooltip_opacity] number args.opacity The tooltip opacity.
+-- @tparam[opt=beautiful.tooltip_gaps] table|number args.gaps The tooltip margins.
 -- @treturn awful.tooltip The created tooltip.
 -- @see add_to_object
 -- @see timeout
@@ -633,6 +655,8 @@ end
 -- @see align
 -- @constructorfct awful.tooltip
 function tooltip.new(args)
+    args = args or {}
+
     -- gears.object, properties are linked to set_/get_ functions
     local self = object {
         enable_properties = true,

lib/awful/util.lua

@@ -1,5 +1,8 @@
 ---------------------------------------------------------------------------
---- Utility module for awful.
+--- Various small utility functions not worth putting into new modules.
+--
+-- Most functions in this module are eventually moved into new modules are
+-- deprecated.
 --
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008 Julien Danjou
@@ -19,11 +22,7 @@ local gstring = require("gears.string")
 local grect = require("gears.geometry").rectangle
 local gcolor = require("gears.color")
 local gfs = require("gears.filesystem")
-local capi =
-{
-    awesome = awesome,
-    mouse = mouse
-}
+local capi = { awesome = awesome }
 local gdebug = require("gears.debug")
 local gmath = require("gears.math")
 
@@ -38,6 +37,7 @@ util.shell = os.getenv("SHELL") or "/bin/sh"
 -- This function implementation **has been removed** and no longer
 -- do anything. Use `awful.spawn.easy_async`.
 -- @deprecated awful.util.pread
+-- @see awful.spawn.easy_async
 
 --- Display a deprecation notice, but only once per traceback.
 -- @deprecated deprecate
@@ -99,6 +99,12 @@ function util.mkdir(dir)
 end
 
 --- Eval Lua code.
+--
+-- It can either be "real" code or expressions like `2 ~= 3`.
+-- If the expression cannot be interpreted or returns false, this
+-- function calls `error`.
+--
+-- @tparam string code The code to evaluate.
 -- @return The return value of Lua code.
 -- @staticfct awful.util.eval
 function util.eval(s)
@@ -128,7 +134,7 @@ end
 
 --- Check if a file is a Lua valid file.
 -- This is done by loading the content and compiling it with loadfile().
--- @param path The file path.
+-- @tparam string path The file path.
 -- @return A function if everything is alright, a string with the error
 -- otherwise.
 -- @staticfct awful.util.checkfile
@@ -222,13 +228,16 @@ function util.getdir(d)
 end
 
 --- Search for an icon and return the full path.
+--
 -- It searches for the icon path under the given directories with respect to the
 -- given extensions for the icon filename.
--- @param iconname The name of the icon to search for.
--- @param exts Table of image extensions allowed, otherwise { 'png', gif' }
--- @param dirs Table of dirs to search, otherwise { '/usr/share/pixmaps/' }
+-- @tparam string iconname The name of the icon to search for.
+-- @tparam[opt={'png','gif'}] table exts Table of image extensions allowed.
+-- @tparam[opt={'/usr/share/pixmaps/','/usr/share/icons/hicolor/'}] table dirs
+--  Table of dirs to search.
 -- @tparam[opt] string size The size. If this is specified, subdirectories `x`
 --   of the dirs are searched first.
+-- @treturn string|nil The icon path or `nil` if not found.
 -- @staticfct awful.util.geticonpath
 function util.geticonpath(iconname, exts, dirs, size)
     exts = exts or { 'png', 'gif' }
@@ -326,8 +335,8 @@ end
 --
 -- Note that this method doesn't copy entries found in `__index`.
 -- @deprecated util.table.crush
--- @tparam table t the table to be overridden
--- @tparam table set the table used to override members of `t`
+-- @tparam table t The table to be overridden
+-- @tparam table set The table used to override members of `t`
 -- @tparam[opt=false] boolean raw Use rawset (avoid the metatable)
 -- @treturn table t (for convenience)
 -- @see gears.table
@@ -387,7 +396,7 @@ end
 
 --- Get a sorted table with all keys from a table.
 -- @deprecated util.table.keys
--- @param t the table for which the keys to get
+-- @param t The table for which the keys to get
 -- @return A table with keys
 -- @see gears.table
 function util.table.keys(t)
@@ -398,7 +407,7 @@ end
 --- Filter a tables keys for certain content types
 -- @deprecated util.table.keys_filter
 -- @param t The table to retrieve the keys for
--- @param ... the types to look for
+-- @param ... The types to look for
 -- @return A filtered table with keys
 -- @see gears.table
 function util.table.keys_filter(t, ...)
@@ -408,7 +417,7 @@ end
 
 --- Reverse a table
 -- @deprecated util.table.reverse
--- @param t the table to reverse
+-- @param t The table to reverse
 -- @return the reversed table
 -- @see gears.table
 function util.table.reverse(t)
@@ -418,7 +427,7 @@ end
 
 --- Clone a table
 -- @deprecated util.table.clone
--- @param t the table to clone
+-- @param t The table to clone
 -- @param deep Create a deep clone? (default: true)
 -- @return a clone of t
 -- @see gears.table
@@ -432,9 +441,9 @@ end
 -- given index, all elements of a table that match a given criteria.
 --
 -- @deprecated util.table.iterate
--- @param t      the table to iterate
--- @param filter a function that returns true to indicate a positive match
--- @param start  what index to start iterating from.  Default is 1 (=> start of
+-- @tparam table t The table to iterate.
+-- @tparam function filter A function that returns true to indicate a positive match
+-- @param start What index to start iterating from. Default is 1 (=> start of
 -- the table)
 -- @see gears.table
 function util.table.iterate(t, filter, start)
@@ -445,8 +454,8 @@ end
 
 --- Merge items from the one table to another one
 -- @deprecated util.table.merge
--- @tparam table t the container table
--- @tparam table set the mixin table
+-- @tparam table t The container table
+-- @tparam table set The mixin table
 -- @treturn table Return `t` for convenience
 -- @see gears.table
 function util.table.merge(t, set)

lib/awful/wallpaper.lua

@@ -329,7 +329,6 @@ local function paint()
                     cr:rectangle(area.x, area.y, area.width, area.height)
                     cr:fill()
                 end
-
             end
 
             if not wall._private.container then
@@ -413,7 +412,7 @@ end)
 -- wallpaper will be defined as a normal `wibox` widget tree.
 --
 -- @property widget
--- @tparam wibox.widget widget
+-- @tparam[opt=nil] widget|nil widget
 -- @see wibox.widget.imagebox
 -- @see wibox.container.tile
 
@@ -434,7 +433,9 @@ end)
 -- @DOC_awful_wallpaper_dpi1_EXAMPLE@
 --
 -- @property dpi
--- @tparam[opt=screen.dpi] number dpi
+-- @tparam[opt=self.screen.dpi] number dpi
+-- @propertyunit pixel\_per\_inch
+-- @negativeallowed false
 -- @see screen
 -- @see screen.dpi
 
@@ -445,6 +446,7 @@ end)
 --
 -- @property screen
 -- @tparam screen screen
+-- @propertydefault Obtained from the constructor.
 -- @see screens
 -- @see add_screen
 -- @see remove_screen
@@ -455,7 +457,8 @@ end)
 --
 -- Some large wallpaper are made to span multiple screens.
 -- @property screens
--- @tparam table screens
+-- @tparam[opt={self.screen}] table screens
+-- @tablerowtype A list of `screen` objects.
 -- @see screen
 -- @see add_screen
 -- @see remove_screen
@@ -464,12 +467,13 @@ end)
 --- The background color.
 --
 -- It will be used as the "fill" color if the `image` doesn't take all the
--- screen space. It will also be the default background for the `widget.
+-- screen space. It will also be the default background for the `widget`.
 --
 -- As usual with colors in `AwesomeWM`, it can also be a gradient or a pattern.
 --
 -- @property bg
--- @tparam gears.color bg
+-- @tparam[opt=beautiful.wallpaper_bg] color bg
+-- @usebeautiful beautiful.wallpaper_bg
 -- @see gears.color
 
 --- The foreground color.
@@ -479,12 +483,13 @@ end)
 -- As usual with colors in `AwesomeWM`, it can also be a gradient or a pattern.
 --
 -- @property fg
--- @tparam gears.color fg
+-- @tparam[opt=beautiful.wallpaper_fg] color fg
 -- @see gears.color
 
 --- The default wallpaper background color.
 -- @beautiful beautiful.wallpaper_bg
--- @tparam gears.color wallpaper_bg
+-- @tparam color wallpaper_bg
+-- @usebeautiful beautiful.wallpaper_fg
 -- @see bg
 
 --- The default wallpaper foreground color.
@@ -519,18 +524,23 @@ end)
 -- @DOC_awful_wallpaper_padding1_EXAMPLE@
 --
 -- @property honor_padding
--- @tparam boolean honor_padding
+-- @tparam[opt=false] boolean honor_padding
 -- @see honor_workarea
 -- @see uncovered_areas
 
 --- Returns the list of screen(s) area which won't be covered by the wallpaper.
 --
 -- When `honor_workarea`, `honor_padding` or panning are used, some section of
--- the screen won't have a wallpaper. This returns a list of areas tables. Each
--- table has a `x`, `y`, `width` and `height` key.
+-- the screen won't have a wallpaper.
 --
 -- @property uncovered_areas
 -- @tparam table uncovered_areas
+-- @propertydefault This depends on the `honor_workarea` and `honor_padding` values.
+-- @tablerowtype A list of area tables with the following keys:
+-- @tablerowkey number x
+-- @tablerowkey number y
+-- @tablerowkey number width
+-- @tablerowkey number height
 -- @see honor_workarea
 -- @see honor_padding
 -- @see uncovered_areas_color
@@ -545,7 +555,7 @@ end)
 -- color or a gradient.
 --
 -- @property uncovered_areas_color
--- @tparam gears.color uncovered_areas_color
+-- @tparam[opt="transparent"] color uncovered_areas_color
 -- @see uncovered_areas
 
 --- Defines where the wallpaper is placed when there is multiple screens.
@@ -590,7 +600,15 @@ end)
 -- @DOC_awful_wallpaper_panning_custom_EXAMPLE@
 --
 -- @property panning_area
--- @tparam function|string panning_area
+-- @tparam[opt="outer"] function|string panning_area
+-- @propertytype string A panning algorithm
+-- @propertyvalue "outer"
+-- @propertyvalue "inner"
+-- @propertyvalue "inner_horizontal"
+-- @propertyvalue "inner_vertical"
+-- @propertytype function Custom panning function.
+-- @functionparam awful.wallpaper wallpaper The wallpaper object.
+-- @functionreturn A table with `x`, `y`, `width` and `height` keys,
 -- @see uncovered_areas
 
 function module:set_panning_area(value)
@@ -711,6 +729,7 @@ end
 --
 -- @method add_screen
 -- @tparam screen screen The screen object.
+-- @noreturn
 -- @see remove_screen
 function module:add_screen(s)
     s = get_screen(s)
@@ -739,6 +758,7 @@ end
 -- wallpaper will have an overlap.
 --
 -- @method detach
+-- @noreturn
 -- @see remove_screen
 -- @see add_screen
 function module:detach()
@@ -762,6 +782,7 @@ end
 -- really need to repaint the wallpaper, call this method.
 --
 -- @method repaint
+-- @noreturn
 function module:repaint()
     for _, s in ipairs(self._private.screens) do
         pending_repaint[s] = true
@@ -789,21 +810,28 @@ end
 --
 -- @method remove_screen
 -- @tparam screen screen The screen to remove.
+-- @treturn boolean `true` if the screen was removed and `false` if the screen
+--  wasn't found.
 -- @see detach
 -- @see add_screen
 -- @see screens
 function module:remove_screen(s)
+    local ret =  false
+
     s = get_screen(s)
 
     for k, s2 in ipairs(self._private.screens) do
         if s == s2 then
             table.remove(self._private.screens, k)
+            ret = true
         end
     end
 
     backgrounds[s] = nil
 
     self:repaint()
+
+    return ret
 end
 
 --- Create a wallpaper.

lib/awful/wibar.lua

@@ -62,25 +62,22 @@ local align_map = {
 -- @DOC_awful_wibar_stretch_EXAMPLE@
 --
 -- @property stretch
--- @tparam boolean stretch
+-- @tparam[opt=true] boolean|nil stretch
 -- @propbeautiful
 -- @propemits true false
 -- @see align
 
 --- How to align non-stretched wibars.
 --
--- Values are:
---
---  * `"top"`
---  * `"bottom"`
---  * `"left"`
---  * `"right"`
---  * `"centered"`
---
 --  @DOC_awful_wibar_align_EXAMPLE@
 --
 -- @property align
--- @tparam string align
+-- @tparam[opt="centered"] string|nil align
+-- @propertyvalue "top"
+-- @propertyvalue "bottom"
+-- @propertyvalue "left"
+-- @propertyvalue "right"
+-- @propertyvalue "centered"
 -- @propbeautiful
 -- @propemits true false
 -- @see stretch
@@ -93,7 +90,16 @@ local align_map = {
 -- @DOC_awful_wibar_margins_EXAMPLE@
 --
 -- @property margins
--- @tparam number|table margins
+-- @tparam[opt=0] number|table|nil margins
+-- @tparam[opt=0] number margins.left
+-- @tparam[opt=0] number margins.right
+-- @tparam[opt=0] number margins.top
+-- @tparam[opt=0] number margins.bottom
+-- @negativeallowed true
+-- @propertytype number A single value for each side.
+-- @propertytype table A different value for each side.
+-- @propertytype nil Fallback to `beautiful.wibar_margins`.
+-- @propertyunit pixel
 -- @propbeautiful
 -- @propemits true false
 
@@ -281,17 +287,14 @@ end
 
 --- The wibox position.
 --
--- The valid values are:
---
--- * left
--- * right
--- * top
--- * bottom
---
 -- @DOC_awful_wibar_position_EXAMPLE@
 --
 -- @property position
--- @tparam string position Either "left", right", "top" or "bottom"
+-- @tparam[opt="top"] string position
+-- @propertyvalue "left"
+-- @propertyvalue "right"
+-- @propertyvalue "top"
+-- @propertyvalue "bottom"
 -- @propemits true false
 
 function awfulwibar.get_position(wb)
@@ -442,6 +445,7 @@ end
 
 --- Remove a wibar.
 -- @method remove
+-- @noreturn
 
 function awfulwibar.remove(self)
     self.visible = false
@@ -537,6 +541,19 @@ end
 --@DOC_wibox_constructor_COMMON@
 -- @return The new wibar
 -- @constructorfct awful.wibar
+-- @usebeautiful beautiful.wibar_favor_vertical
+-- @usebeautiful beautiful.wibar_border_width
+-- @usebeautiful beautiful.wibar_border_color
+-- @usebeautiful beautiful.wibar_ontop
+-- @usebeautiful beautiful.wibar_cursor
+-- @usebeautiful beautiful.wibar_opacity
+-- @usebeautiful beautiful.wibar_type
+-- @usebeautiful beautiful.wibar_width
+-- @usebeautiful beautiful.wibar_height
+-- @usebeautiful beautiful.wibar_bg
+-- @usebeautiful beautiful.wibar_bgimage
+-- @usebeautiful beautiful.wibar_fg
+-- @usebeautiful beautiful.wibar_shape
 function awfulwibar.new(args)
     args = args or {}
     local position = args.position or "top"
@@ -658,10 +675,6 @@ function awfulwibar.mt:__index(_, k)
     end
 end
 
---@DOC_wibox_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(awfulwibar, awfulwibar.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/awful/widget/button.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
--- A simple button widget.
+-- A simple button widget based on a background image.
 --
 -- @DOC_wibox_awidget_defaults_button_EXAMPLE@
 --

lib/awful/widget/calendar_popup.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
--- A calendar popup wibox.
+-- A popup wibox containing a `wibox.widget.calendar` widget.
 --
 -- Display a month or year calendar popup using `calendar_popup.month` or `calendar_popup.year`.
 -- The calendar style can be tweaked by providing tables of style properties at creation:
@@ -141,8 +141,10 @@ local function parse_cell_options(cell, args)
         props[prop] = args[prop] or beautiful["calendar_" .. cell .. "_" .. prop] or bl_style[prop] or default
     end
     if cell == "focus" and props.markup == nil then
-        local fg = props.fg_color and string.format('foreground="%s"', props.fg_color) or ""
-        local bg = props.bg_color and string.format('background="%s"', props.bg_color) or ""
+        local fg = props.fg_color
+            and string.format('foreground="%s"', gears.color.to_rgba_string(props.fg_color)) or ""
+        local bg = props.bg_color
+            and string.format('background="%s"', gears.color.to_rgba_string(props.bg_color)) or ""
         props.markup = string.format(
             '<span %s %s><b>%s</b></span>',
             fg, bg, "%s"
@@ -238,10 +240,12 @@ function calendar_popup:call_calendar(offset, position, screen)
 end
 
 --- Toggle calendar visibility.
+-- @treturn boolean The new value of `visible`.
 -- @method toggle
 function calendar_popup:toggle()
     self:call_calendar(0)
     self.visible = not self.visible
+    return self.visible
 end
 
 --- Attach the calendar to a widget to display at a specific position.
@@ -384,6 +388,7 @@ end
 -- @tparam table args.style_focus Cell style for the current day cell (see `cell_properties`)
 -- @treturn wibox A wibox containing the calendar
 -- @constructorfct awful.widget.calendar_popup.month
+-- @usebeautiful beautiful.calendar_style
 function calendar_popup.month(args)
     return get_cal_wibox("month", args)
 end
@@ -426,4 +431,4 @@ end
 
 return setmetatable(calendar_popup, calendar_popup.mt)
 
--- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/awful/widget/clienticon.lua

@@ -86,7 +86,7 @@ end
 --- The widget's @{client}.
 --
 -- @property client
--- @param client
+-- @tparam[opt=nil] client|nil client
 -- @propemits true false
 
 function clienticon:get_client()

lib/awful/widget/common.lua

@@ -1,4 +1,10 @@
 ---------------------------------------------------------------------------
+-- This module contains helper functions to manage a layout widgets.
+--
+-- This is the boilerplate code to manage a "list" of objects and display
+-- them in a `wibox.layout`. It uses signals to detect when an object change
+-- and its widget be updated.
+--
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
 -- @classmod awful.widget.common

lib/awful/widget/keyboardlayout.lua

@@ -1,7 +1,11 @@
 ---------------------------------------------------------------------------
+-- Display the current keyboard layout name in a widget.
+--
+--
 -- @author Aleksey Fedotov <lexa@cfotr.com>
 -- @copyright 2015 Aleksey Fedotov
 -- @widgetmod awful.widget.keyboardlayout
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local capi = {awesome = awesome}
@@ -132,7 +136,7 @@ end
 -- Create an array whose element is a table consisting of the four fields:
 -- vendor, file, section and group_idx, which all correspond to the
 -- xkb_symbols pattern "vendor/file(section):group_idx".
--- @tparam string group_names The string awesome.xkb_get_group_names() returns.
+-- @tparam string group_names The string `awesome.xkb_get_group_names()` returns.
 -- @treturn table An array of tables whose keys are vendor, file, section, and group_idx.
 -- @staticfct awful.keyboardlayout.get_groups_from_group_names
 function keyboardlayout.get_groups_from_group_names(group_names)
@@ -253,6 +257,7 @@ local function update_layout(self)
 end
 
 --- Select the next layout.
+-- @noreturn
 -- @method next_layout
 
 --- Create a keyboard layout widget.
@@ -260,7 +265,7 @@ end
 -- It shows current keyboard layout name in a textbox.
 --
 -- @constructorfct awful.widget.keyboardlayout
--- @return A keyboard layout widget.
+-- @treturn awful.widget.keyboardlayout A keyboard layout widget.
 function keyboardlayout.new()
     local widget = textbox()
     local self = widget_base.make_widget(widget, nil, {enable_properties=true})
@@ -313,9 +318,6 @@ function keyboardlayout.mt:__call(...)
     return _instance
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
 
 return setmetatable(keyboardlayout, keyboardlayout.mt)
 

lib/awful/widget/layoutbox.lua

@@ -47,6 +47,7 @@ end
 
 --- Create a layoutbox widget. It draws a picture with the current layout
 -- symbol of the current tag.
+-- @constructorfct awful.widget.layoutbox
 -- @tparam table args The arguments.
 -- @tparam screen args.screen The screen number that the layout will be represented for.
 -- @tparam table args.buttons The `awful.button`s for this layoutbox.
@@ -114,10 +115,6 @@ function layoutbox.mt:__call(...)
     return layoutbox.new(...)
 end
 
---@DOC_widget_COMMON@
-
---@DOC_object_COMMON@
-
 return setmetatable(layoutbox, layoutbox.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/awful/widget/layoutlist.lua

@@ -33,6 +33,7 @@ local gtable   = require("gears.table")
 local beautiful= require("beautiful")
 local alayout  = require("awful.layout")
 local surface  = require("gears.surface")
+local gcolor   = require("gears.color")
 
 local module = {}
 
@@ -84,7 +85,7 @@ local function wb_label(item, _, textbox)
     local text = ""
 
     if item.name then
-        text = "<span color='"..fg.."'>"..item.name..'</span>'
+        text = "<span color='"..gcolor.ensure_pango_color(fg, "#000000").."'>"..item.name..'</span>'
     end
 
     return text, bg, nil, item.icon, {
@@ -177,33 +178,37 @@ end
 local layoutlist = {}
 
 --- The layoutlist default widget layout.
+--
 -- If no layout is specified, a `wibox.layout.fixed.vertical` will be created
 -- automatically.
 -- @property base_layout
--- @param widget
+-- @tparam[opt=wibox.layout.fixed.vertical] wibox.layout base_layout
 -- @propemits true false
 -- @see wibox.layout.fixed.vertical
 -- @see base_layout
 
 --- The delegate widget template.
+--
 -- @property widget_template
--- @param table
+-- @tparam[opt=nil] template|nil widget_template
 -- @propemits true false
 
 --- The layoutlist screen.
+--
 -- @property screen
--- @param screen
+-- @tparam screen screen
+-- @propertydefault Obtained from the constructor.
 
 --- A function that returns the list of layout to display.
 --
 -- @property source
--- @param[opt=awful.widget.layoutlist.source.for_screen] function
-
---- The layoutlist filter function.
--- @property filter
--- @param[opt=awful.widget.layoutlist.source.for_screen] function
+-- @tparam[opt=awful.widget.layoutlist.source.for_screen] function source
+-- @functionparam screen s The layoutlist screen.
+-- @functionparam table metadata Various metadata.
+-- @functionreturn table The list of layouts.
 
 --- The default foreground (text) color.
+--
 -- @beautiful beautiful.layoutlist_fg_normal
 -- @tparam[opt=nil] string|pattern fg_normal
 -- @see gears.color
@@ -237,7 +242,7 @@ local layoutlist = {}
 
 --- The selected layout alignment.
 -- @beautiful beautiful.layoutlist_align
--- @tparam[opt=left] string align *left*, *right* or *center*
+-- @tparam[opt="left"] string align *left*, *right* or *center*
 
 --- The selected layout title font.
 -- @beautiful beautiful.layoutlist_font_selected
@@ -275,16 +280,35 @@ local layoutlist = {}
 
 --- The currenly displayed layouts.
 -- @property layouts
--- @param table
+-- @tparam[opt={}] table layouts
+-- @tablerowtype A list of `awful.layout.suit`.
 
 --- The currently selected layout.
 -- @property current_layout
--- @param layout
+-- @tparam[opt=nil] layout|nil current_layout
+-- @readonly
+
+--- The current number of layouts.
+--
+-- @property count
+-- @readonly
+-- @tparam number count The number of layouts.
+-- @propertydefault This current number of layouts.
+-- @negativeallowed false
+-- @propemits true false
 
 function layoutlist:get_layouts()
     local f = self.source or self._private.source or module.source.for_screen
 
-    return f(self.screen)
+    local ret = f(self.screen)
+
+    if self._private.last_count ~= #ret then
+        self:emit_signal("property::count", ret, self._private.last_count)
+
+        self._private.last_count = ret
+    end
+
+    return ret
 end
 
 function layoutlist:get_current_layout()
@@ -329,6 +353,14 @@ function layoutlist:set_base_layout(layout)
     self:emit_signal("property::base_layout", layout)
 end
 
+function layoutlist:get_count()
+    if not self._private.last_count then
+        self._do_()
+    end
+
+    return self._private.last_count
+end
+
 function layoutlist:set_widget_template(widget_template)
     self._private.widget_template = widget_template
 
@@ -371,22 +403,22 @@ end
 -- @tparam[opt] table args.widget_template A custom widget to be used for each action.
 -- @tparam[opt=ascreen.focused()] screen args.screen A screen
 -- @tparam[opt={}] table args.style Extra look and feel parameters
--- @tparam boolean args.style.disable_icon
--- @tparam boolean args.style.disable_name
--- @tparam string|pattern args.style.fg_normal
--- @tparam string|pattern args.style.bg_normal
--- @tparam string|pattern args.style.fg_selected
--- @tparam string|pattern args.style.bg_selected
--- @tparam string args.style.font
--- @tparam string args.style.font_selected
--- @tparam string args.style.align *left*, *right* or *center*
--- @tparam number args.style.spacing
--- @tparam gears.shape args.style.shape
--- @tparam number args.style.shape_border_width
--- @tparam string|pattern args.style.shape_border_color
--- @tparam gears.shape args.style.shape_selected
--- @tparam string|pattern args.style.shape_border_width_selected
--- @tparam string|pattern args.style.shape_border_color_selected
+-- @tparam[opt=beautiful.layoutlist_disable_icon] boolean args.style.disable_icon
+-- @tparam[opt=beautiful.layoutlist_disable_name] boolean args.style.disable_name
+-- @tparam[opt=beautiful.layoutlist_fg_normal] string|pattern args.style.fg_normal
+-- @tparam[opt=beautiful.layoutlist_bg_normal] string|pattern args.style.bg_normal
+-- @tparam[opt=beautiful.layoutlist_fg_selected] string|pattern args.style.fg_selected
+-- @tparam[opt=beautiful.layoutlist_bg_selected] string|pattern args.style.bg_selected
+-- @tparam[opt=beautiful.layoutlist_font] string args.style.font
+-- @tparam[opt=beautiful.layoutlist_font_selected] string args.style.font_selected
+-- @tparam[opt=beautiful.layoutlist_align] string args.style.align *left*, *right* or *center*
+-- @tparam[opt=beautiful.layoutlist_spacing] number args.style.spacing
+-- @tparam[opt=beautiful.layoutlist_shape] gears.shape args.style.shape
+-- @tparam[opt=beautiful.layoutlist_shape_border_width] number args.style.shape_border_width
+-- @tparam[opt=beautiful.layoutlist_shape_border_color] string|pattern args.style.shape_border_color
+-- @tparam[opt=beautiful.layoutlist_shape_selected] gears.shape args.style.shape_selected
+-- @tparam[opt=beautiful.layoutlist_shape_border_width_selected] string|pattern args.style.shape_border_width_selected
+-- @tparam[opt=beautiful.layoutlist_shape_border_color_selected] string|pattern args.style.shape_border_color_selected
 -- @treturn widget The action widget.
 -- @constructorfct awful.widget.layoutlist
 

lib/awful/widget/only_on_screen.lua

@@ -50,7 +50,7 @@ end
 
 --- The widget to be displayed
 -- @property widget
--- @tparam widget widget The widget
+-- @tparam[opt=nil] widget|nil widget
 
 only_on_screen.set_widget = base.set_widget_common
 
@@ -66,10 +66,11 @@ function only_on_screen:set_children(children)
     self:set_widget(children[1])
 end
 
---- The screen to display on. Can be a screen object, a screen index, a screen
+--- The screen to display on.
+-- Can be a screen object, a screen index, a screen
 -- name ("VGA1") or the string "primary" for the primary screen.
 -- @property screen
--- @tparam screen|string|integer screen The screen.
+-- @tparam[opt="primary"] screen screen
 
 function only_on_screen:set_screen(s)
     self._private.screen = s
@@ -80,11 +81,11 @@ function only_on_screen:get_screen()
     return self._private.screen
 end
 
---- Returns a new only_on_screen container.
+--- Returns a new `awful.widget.only_on_screen` container.
 -- This widget makes some other widget visible on just some screens. Use
 -- `:set_widget()` to set the widget and `:set_screen()` to set the screen.
--- @param[opt] widget The widget to display.
--- @param[opt] s The screen to display on.
+-- @tparam[opt=nil] widget widget The widget to display.
+-- @tparam[opt="primary"] screen s The screen to display on.
 -- @treturn table A new only_on_screen container
 -- @constructorfct awful.widget.only_on_screen
 local function new(widget, s)

lib/awful/widget/prompt.lua

@@ -73,7 +73,7 @@ end
 -- of `awful.spawn`. Depending on the amount of customization to your shell
 -- environment, this can increase startup time.
 -- @property with_shell
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean with_shell
 
 --- Create a prompt widget which will launch a command.
 -- For additional documentation about `args` parameter, please refer to
@@ -85,10 +85,10 @@ end
 --   Prompt background color.
 -- @tparam[opt=`beautiful.prompt_fg` or `beautiful.fg_normal`] color args.fg
 --   Prompt foreground color.
--- @tparam[opt] gears.color args.fg_cursor
--- @tparam[opt] gears.color args.bg_cursor
+-- @tparam[opt=beautiful.prompt_fg_cursor] gears.color args.fg_cursor
+-- @tparam[opt=beautiful.prompt_bg_cursor] gears.color args.bg_cursor
 -- @tparam[opt] gears.color args.ul_cursor
--- @tparam[opt] string args.font
+-- @tparam[opt=beautiful.prompt_font] string args.font
 -- @tparam[opt] boolean args.autoexec
 -- @tparam[opt] function args.highlighter A function to add syntax highlighting
 --   to the command.
@@ -116,6 +116,10 @@ end
 -- @return An instance of prompt widget, inherits from
 --   `wibox.container.background`.
 -- @constructorfct awful.widget.prompt
+-- @usebeautiful beautiful.prompt_fg
+-- @usebeautiful beautiful.prompt_bg
+-- @usebeautiful beautiful.fg_normal When `beautiful.prompt_fg` isn't set.
+-- @usebeautiful beautiful.bg_normal When `beautiful.prompt_bg` isn't set.
 function widgetprompt.new(args)
     args = args or {}
     local promptbox = background()

lib/awful/widget/taglist.lua

@@ -35,6 +35,7 @@
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
 -- @widgetmod awful.widget.taglist
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -54,6 +55,7 @@ local gcolor = require("gears.color")
 local gstring = require("gears.string")
 local gdebug = require("gears.debug")
 local base = require("wibox.widget.base")
+local gtable = require("gears.table")
 
 local function get_screen(s)
     return s and capi.screen[s]
@@ -64,22 +66,22 @@ taglist.filter, taglist.source = {}, {}
 
 --- The tag list main foreground (text) color.
 -- @beautiful beautiful.taglist_fg_focus
--- @param[opt=fg_focus] color
+-- @param[opt=beautiful.fg_focus] color
 -- @see gears.color
 
 --- The tag list main background color.
 -- @beautiful beautiful.taglist_bg_focus
--- @param[opt=bg_focus] color
+-- @param[opt=beautiful.bg_focus] color
 -- @see gears.color
 
 --- The tag list urgent elements foreground (text) color.
 -- @beautiful beautiful.taglist_fg_urgent
--- @param[opt=fg_urgent] color
+-- @param[opt=beautiful.fg_urgent] color
 -- @see gears.color
 
 --- The tag list urgent elements background color.
 -- @beautiful beautiful.taglist_bg_urgent
--- @param[opt=bg_urgent] color
+-- @param[opt=beautiful.bg_urgent] color
 -- @see gears.color
 
 --- The tag list occupied elements background color.
@@ -250,7 +252,7 @@ function taglist.taglist_label(t, args)
     local taglist_squares_unsel_empty = args.squares_unsel_empty or theme.taglist_squares_unsel_empty
     local taglist_squares_resize = theme.taglist_squares_resize or args.squares_resize or "true"
     local taglist_disable_icon = args.taglist_disable_icon or theme.taglist_disable_icon or false
-    local font = args.font or theme.taglist_font or theme.font or ""
+    local font = args.font or theme.taglist_font or theme.font
     local text = nil
     local sel = capi.client.focus
     local bg_color = nil
@@ -360,7 +362,7 @@ function taglist.taglist_label(t, args)
     end
 
     if not tag.getproperty(t, "icon_only") then
-        text = "<span font_desc='"..font.."'>"
+        text = "<span font_desc='"..(font or "").."'>"
         if fg_color then
             text = text .. "<span color='" .. gcolor.ensure_pango_color(fg_color) ..
                 "'>" .. (gstring.xml_escape(t.name) or "") .. "</span>"
@@ -390,10 +392,10 @@ local function create_callback(w, t)
     common._set_common_property(w, "tag", t)
 end
 
-local function taglist_update(s, w, buttons, filter, data, style, update_function, args)
+local function taglist_update(s, self, buttons, filter, data, style, update_function, args)
     local tags = {}
 
-    local source = args and args.source or taglist.source.for_screen or nil
+    local source = self._private.source or taglist.source.for_screen or nil
     local list   = source and source(s, args) or s.tags
 
     for _, t in ipairs(list) do
@@ -402,14 +404,147 @@ local function taglist_update(s, w, buttons, filter, data, style, update_functio
         end
     end
 
+    if self._private.last_count ~= #tags then
+        self:emit_signal("property::count", #tags, self._private.last_count)
+        self._private.last_count = #tags
+    end
+
     local function label(c) return taglist.taglist_label(c, style) end
 
-    update_function(w, buttons, label, data, tags, {
-        widget_template = args.widget_template,
+    update_function(self._private.base_layout, buttons, label, data, tags, {
+        widget_template = self._private.widget_template,
         create_callback = create_callback,
     })
 end
 
+--- The taglist screen.
+--
+-- @property screen
+-- @propertydefault Obtained from the constructor.
+-- @tparam screen screen
+
+--- Set the taglist layout.
+--
+-- @property base_layout
+-- @tparam[opt=wibox.layout.fixed.horizontal] wibox.layout base_layout
+-- @see wibox.layout.fixed.horizontal
+
+--- The current number of tags.
+--
+-- Note that the `tasklist` is usually lazy-loaded. Reading this property
+-- may cause the widgets to be created. Depending on where the property is called
+-- from, it might, in theory, cause an infinite loop.
+--
+-- @property count
+-- @readonly
+-- @tparam number count The number of tags.
+-- @propertydefault This current number of tags.
+-- @negativeallowed false
+-- @propemits true false
+
+function taglist:set_base_layout(layout)
+    self._private.base_layout = base.make_widget_from_value(
+        layout or fixed.horizontal
+    )
+
+    local spacing = self._private.style.spacing or beautiful.taglist_spacing
+
+    if self._private.base_layout.set_spacing and spacing then
+        self._private.base_layout:set_spacing(spacing)
+    end
+
+    assert(self._private.base_layout.is_widget)
+
+    self._do_taglist_update()
+
+    self:emit_signal("widget::layout_changed")
+    self:emit_signal("widget::redraw_needed")
+    self:emit_signal("property::base_layout", layout)
+end
+
+function taglist:get_count()
+    if not self._private.last_count then
+        self._do_taglist_update_now()
+    end
+
+    return self._private.last_count
+end
+
+function taglist:layout(_, width, height)
+    if self._private.base_layout then
+        return { base.place_widget_at(self._private.base_layout, 0, 0, width, height) }
+    end
+end
+
+function taglist:fit(context, width, height)
+    if not self._private.base_layout then
+        return 0, 0
+    end
+
+    return base.fit_widget(self, context, self._private.base_layout, width, height)
+end
+
+--- An alternative function to configure the content.
+--
+-- You should use `widget_template` if it fits your use case first. This
+-- API is very low level.
+--
+-- @property update_function
+-- @tparam function update_function
+-- @propertydefault The default function delegate everything to the `widget_template`.
+-- @functionparam widget layout The base layout object.
+-- @functionparam table buttons The buttons for this tag entry (see below).
+-- @functionparam string label The tag name.
+-- @functionparam table data Arbitrary metadate.
+-- @functionparam table tags The list of tags (ordered).
+-- @functionparam table metadata Other values.
+-- @functionnoreturn
+
+--- A function to restrict the content of the taglist.
+--
+-- @property filter
+-- @tparam[opt=nil] function|nil filter
+-- @functionparam tag t The tag to accept or reject.
+-- @functionreturn boolean `true` if the tag is accepter or `false` if it is rejected.
+-- @see source
+-- @see awful.widget.taglist.filter.noempty
+-- @see awful.widget.taglist.filter.selected
+-- @see awful.widget.taglist.filter.all
+-- @see awful.widget.taglist.source.for_screen
+
+--- The function used to gather the group of tags.
+--
+-- @property source
+-- @tparam[opt=awful.widget.taglist.source.for_screen] function source
+-- @functionparam screen s The taglist screen.
+-- @functionparam table metadata Various metadata.
+-- @functionreturn table The list of tags
+-- @see filter
+-- @see awful.widget.taglist.source.for_screen
+
+--- A templete used to genetate the individual tag widgets.
+--
+-- @property widget_template
+-- @tparam[opt=nil] template|nil widget_template
+
+for _, prop in ipairs { "filter", "update_function", "widget_template", "source", "screen" } do
+    taglist["set_"..prop] = function(self, value)
+        if value == self._private[prop] then return end
+
+        self._private[prop] = value
+
+        self._do_taglist_update()
+
+        self:emit_signal("widget::layout_changed")
+        self:emit_signal("widget::redraw_needed")
+        self:emit_signal("property::"..prop, value)
+    end
+
+    taglist["get_"..prop] = function(self)
+        return self._private[prop]
+    end
+end
+
 --- Create a new taglist widget. The last two arguments (update_function
 -- and layout) serve to customize the layout of the taglist (eg. to
 -- make it vertical). For that, you will need to copy the
@@ -428,39 +563,55 @@ end
 --  function used to generate the list of tag.
 -- @tparam[opt] table args.widget_template A custom widget to be used for each tag
 -- @tparam[opt={}] table args.style The style overrides default theme.
--- @tparam[opt=nil] string|pattern args.style.fg_focus
--- @tparam[opt=nil] string|pattern args.style.bg_focus
--- @tparam[opt=nil] string|pattern args.style.fg_urgent
--- @tparam[opt=nil] string|pattern args.style.bg_urgent
--- @tparam[opt=nil] string|pattern args.style.bg_occupied
--- @tparam[opt=nil] string|pattern args.style.fg_occupied
--- @tparam[opt=nil] string|pattern args.style.bg_empty
--- @tparam[opt=nil] string|pattern args.style.fg_empty
--- @tparam[opt=nil] string|pattern args.style.bg_volatile
--- @tparam[opt=nil] string|pattern args.style.fg_volatile
--- @tparam[opt=nil] string args.style.squares_sel
--- @tparam[opt=nil] string args.style.squares_unsel
--- @tparam[opt=nil] string args.style.squares_sel_empty
--- @tparam[opt=nil] string args.style.squares_unsel_empty
--- @tparam[opt=nil] string args.style.squares_resize
--- @tparam[opt=nil] string args.style.disable_icon
--- @tparam[opt=nil] string args.style.font
--- @tparam[opt=nil] number args.style.spacing The spacing between tags.
--- @tparam[opt] string args.style.squares_sel A user provided image for selected squares.
--- @tparam[opt] string args.style.squares_unsel A user provided image for unselected squares.
--- @tparam[opt] string args.style.squares_sel_empty A user provided image for selected squares for empty tags.
--- @tparam[opt] string args.style.squares_unsel_empty A user provided image for unselected squares for empty tags.
--- @tparam[opt] boolean args.style.squares_resize True or false to resize squares.
--- @tparam string|pattern args.style.bg_focus The background color for focused client.
--- @tparam string|pattern args.style.fg_focus The foreground color for focused client.
--- @tparam string|pattern args.style.bg_urgent The background color for urgent clients.
--- @tparam string|pattern args.style.fg_urgent The foreground color for urgent clients.
--- @tparam string args.style.font The font.
+-- @tparam[opt=beautiful.taglist_fg_focus] string|pattern args.style.fg_focus
+-- @tparam[opt=beautiful.taglist_bg_focus] string|pattern args.style.bg_focus
+-- @tparam[opt=beautiful.taglist_fg_urgent] string|pattern args.style.fg_urgent
+-- @tparam[opt=beautiful.taglist_bg_urgent] string|pattern args.style.bg_urgent
+-- @tparam[opt=beautiful.taglist_bg_occupied] string|pattern args.style.bg_occupied
+-- @tparam[opt=beautiful.taglist_fg_occupied] string|pattern args.style.fg_occupied
+-- @tparam[opt=beautiful.taglist_bg_empty] string|pattern args.style.bg_empty
+-- @tparam[opt=beautiful.taglist_fg_empty] string|pattern args.style.fg_empty
+-- @tparam[opt=beautiful.taglist_bg_volatile] string|pattern args.style.bg_volatile
+-- @tparam[opt=beautiful.taglist_fg_volatile] string|pattern args.style.fg_volatile
+-- @tparam[opt=beautiful.taglist_squares_sel] string args.style.squares_sel
+-- @tparam[opt=beautiful.taglist_squares_unsel] string args.style.squares_unsel
+-- @tparam[opt=beautiful.taglist_squares_sel_empty] string args.style.squares_sel_empty
+-- @tparam[opt=beautiful.taglist_squares_unsel_empty] string args.style.squares_unsel_empty
+-- @tparam[opt=beautiful.taglist_squares_resize] string args.style.squares_resize
+-- @tparam[opt=beautiful.taglist_disable_icon] string args.style.disable_icon
+-- @tparam[opt=beautiful.taglist_font] string args.style.font
+-- @tparam[opt=beautiful.taglist_spacing] number args.style.spacing The spacing between tags.
+-- @tparam[opt=beautiful.taglist_squares_sel] string args.style.squares_sel A user
+--  provided image for selected squares.
+-- @tparam[opt=beautiful.taglist_squares_unsel] string args.style.squares_unsel A
+--  user provided image for unselected squares.
+-- @tparam[opt=beautiful.taglist_squares_sel_empty] string args.style.squares_sel_empty A
+-- user provided image for selected squares for empty tags.
+-- @tparam[opt=beautiful.taglist_squares_unsel_empty] string args.style.squares_unsel_empty A
+--  user provided image for unselected squares for empty tags.
+-- @tparam[opt=beautiful.taglist_squares_resize] boolean args.style.squares_resize `true`
+--  or `false` to resize squares.
+-- @tparam[opt=beautiful.taglist_font] string args.style.font The font.
+-- @tparam[opt=beautiful.taglist_shape] gears.shape|function args.style.shape
+-- @tparam[opt=beautiful.taglist_shape_border_width] number args.style.shape_border_width
+-- @tparam[opt=beautiful.taglist_shape_border_color] string args.style.shape_border_color
+-- @tparam[opt=beautiful.taglist_shape_empty] gears.shape|function args.style.shape_empty
+-- @tparam[opt=beautiful.taglist_shape_border_width_empty] number args.style.shape_border_width_empty
+-- @tparam[opt=beautiful.taglist_shape_border_color_empty] string args.style.border_color_empty
+-- @tparam[opt=beautiful.taglist_shape_focus] gears.shape|function args.style.shape_focus
+-- @tparam[opt=beautiful.taglist_shape_border_width_focus] number args.style.shape_border_width_focus
+-- @tparam[opt=beautiful.taglist_shape_border_color_focus] string args.style.shape_border_color_focus
+-- @tparam[opt=beautiful.taglist_shape_urgent] gears.shape|function args.style.shape_urgent
+-- @tparam[opt=beautiful.taglist_shape_border_width_urgent] number args.style.shape_border_width_urgent
+-- @tparam[opt=beautiful.taglist_shape_border_color_urgent] string args.style.shape_border_color_urgent
+-- @tparam[opt=beautiful.taglist_shape_volatile] gears.shape|function args.style.shape_volatile
+-- @tparam[opt=beautiful.taglist_shape_border_width_volatile] number args.style.shape_border_width_volatile
+-- @tparam[opt=beautiful.taglist_shape_border_color_volatile] string args.style.shape_border_color_volatile
 -- @param filter **DEPRECATED** use args.filter
 -- @param buttons **DEPRECATED** use args.buttons
 -- @param style **DEPRECATED** use args.style
 -- @param update_function **DEPRECATED** use args.update_function
--- @param base_widget **DEPRECATED** use args.base_widget
+-- @param base_widget **DEPRECATED** use args.base_layout
 -- @constructorfct awful.widget.taglist
 function taglist.new(args, filter, buttons, style, update_function, base_widget)
 
@@ -495,28 +646,41 @@ function taglist.new(args, filter, buttons, style, update_function, base_widget)
     screen = screen or get_screen(args.screen)
 
     local uf = args.update_function or common.list_update
-    local w = base.make_widget_from_value(args.layout or fixed.horizontal)
 
-    if w.set_spacing and (args.style and args.style.spacing or beautiful.taglist_spacing) then
-        w:set_spacing(args.style and args.style.spacing or beautiful.taglist_spacing)
-    end
+    local w = base.make_widget(nil, nil, {
+        enable_properties = true,
+    })
+
+    gtable.crush(w, taglist, true)
+
+    gtable.crush(w._private, {
+        style           = args.style or {},
+        buttons         = args.buttons,
+        filter          = args.filter,
+        update_function = args.update_function,
+        widget_template = args.widget_template,
+        source          = args.source,
+        screen          = screen
+    })
 
     local data = setmetatable({}, { __mode = 'k' })
 
     local queued_update = {}
 
     function w._do_taglist_update_now()
-        if screen.valid then
-            taglist_update(screen, w, args.buttons, args.filter, data, args.style, uf, args)
+        if w._private.screen.valid then
+            taglist_update(
+                w._private.screen, w, w._private.buttons, w._private.filter, data, args.style, uf, args
+            )
         end
-        queued_update[screen] = false
+        queued_update[w._private.screen] = false
     end
 
     function w._do_taglist_update()
         -- Add a delayed callback for the first update.
-        if not queued_update[screen] then
+        if not queued_update[w._private.screen] then
             timer.delayed_call(w._do_taglist_update_now)
-            queued_update[screen] = true
+            queued_update[w._private.screen] = true
         end
     end
     if instances == nil then
@@ -558,6 +722,9 @@ function taglist.new(args, filter, buttons, style, update_function, base_widget)
             instances[get_screen(s)] = nil
         end)
     end
+
+    w:set_base_layout(args.base_layout or args.layout)
+
     w._do_taglist_update()
     local list = instances[screen]
     if not list then
@@ -605,8 +772,6 @@ function taglist.mt:__call(...)
     return taglist.new(...)
 end
 
---@DOC_widget_COMMON@
-
 --@DOC_object_COMMON@
 
 return setmetatable(taglist, taglist.mt)

lib/awful/widget/tasklist.lua

@@ -14,14 +14,14 @@
 --  <th align='center'>Icon</th>
 --  <th align='center'>Client property</th>
 -- </tr>
--- <tr><td>▪</td><td><a href="./client.html#client.sticky">sticky</a></td></tr>
--- <tr><td>⌃</td><td><a href="./client.html#client.ontop">ontop</a></td></tr>
--- <tr><td>▴</td><td><a href="./client.html#client.above">above</a></td></tr>
--- <tr><td>▾</td><td><a href="./client.html#client.below">below</a></td></tr>
--- <tr><td>✈</td><td><a href="./client.html#client.floating">floating</a></td></tr>
--- <tr><td>+</td><td><a href="./client.html#client.maximized">maximized</a></td></tr>
--- <tr><td>⬌</td><td><a href="./client.html#client.maximized_horizontal">maximized_horizontal</a></td></tr>
--- <tr><td>⬍</td><td><a href="./client.html#client.maximized_vertical">maximized_vertical</a></td></tr>
+-- <tr><td>▪</td><td><a href="../core_components/client.html#sticky">sticky</a></td></tr>
+-- <tr><td>⌃</td><td><a href="../core_components/client.html#ontop">ontop</a></td></tr>
+-- <tr><td>▴</td><td><a href="../core_components/client.html#above">above</a></td></tr>
+-- <tr><td>▾</td><td><a href="../core_components/client.html#below">below</a></td></tr>
+-- <tr><td>✈</td><td><a href="../core_components/client.html#floating">floating</a></td></tr>
+-- <tr><td>+</td><td><a href="../core_components/client.html#maximized">maximized</a></td></tr>
+-- <tr><td>⬌</td><td><a href="../core_components/client.html#maximized_horizontal">maximized_horizontal</a></td></tr>
+-- <tr><td>⬍</td><td><a href="../core_components/client.html#maximized_vertical">maximized_vertical</a></td></tr>
 -- </table>
 --
 -- **Customizing the tasklist:**
@@ -71,6 +71,7 @@
 -- @author Julien Danjou &lt;julien@danjou.info&gt;
 -- @copyright 2008-2009 Julien Danjou
 -- @widgetmod awful.widget.tasklist
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 -- Grab environment we need
@@ -94,6 +95,7 @@ local wmargin = require("wibox.container.margin")
 local wtextbox = require("wibox.widget.textbox")
 local clienticon = require("awful.widget.clienticon")
 local wbackground = require("wibox.container.background")
+local gtable = require("gears.table")
 
 local function get_screen(s)
     return s and screen[s]
@@ -104,41 +106,65 @@ local tasklist = { mt = {} }
 local instances
 
 --- The default foreground (text) color.
+--
+-- @DOC_wibox_awidget_tasklist_style_fg_normal_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_fg_normal
 -- @tparam[opt=nil] string|pattern fg_normal
 -- @see gears.color
 
 --- The default background color.
+--
+-- @DOC_wibox_awidget_tasklist_style_bg_normal_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_bg_normal
 -- @tparam[opt=nil] string|pattern bg_normal
 -- @see gears.color
 
 --- The focused client foreground (text) color.
+--
+-- @DOC_wibox_awidget_tasklist_style_fg_focus_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_fg_focus
 -- @tparam[opt=nil] string|pattern fg_focus
 -- @see gears.color
 
 --- The focused client background color.
+--
+-- @DOC_wibox_awidget_tasklist_style_bg_focus_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_bg_focus
 -- @tparam[opt=nil] string|pattern bg_focus
 -- @see gears.color
 
 --- The urgent clients foreground (text) color.
+--
+-- @DOC_wibox_awidget_tasklist_style_fg_urgent_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_fg_urgent
 -- @tparam[opt=nil] string|pattern fg_urgent
 -- @see gears.color
 
 --- The urgent clients background color.
+--
+-- @DOC_wibox_awidget_tasklist_style_bg_urgent_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_bg_urgent
 -- @tparam[opt=nil] string|pattern bg_urgent
 -- @see gears.color
 
 --- The minimized clients foreground (text) color.
+--
+-- @DOC_wibox_awidget_tasklist_style_fg_minimize_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_fg_minimize
 -- @tparam[opt=nil] string|pattern fg_minimize
 -- @see gears.color
 
 --- The minimized clients background color.
+--
+-- @DOC_wibox_awidget_tasklist_style_bg_minimize_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_bg_minimize
 -- @tparam[opt=nil] string|pattern bg_minimize
 -- @see gears.color
@@ -160,10 +186,16 @@ local instances
 -- @tparam[opt=nil] string bg_image_minimize
 
 --- Disable the tasklist client icons.
+--
+-- @DOC_wibox_awidget_tasklist_style_disable_icon_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_disable_icon
 -- @tparam[opt=false] boolean tasklist_disable_icon
 
 --- Disable the tasklist client titles.
+--
+-- @DOC_wibox_awidget_tasklist_style_disable_task_name_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_disable_task_name
 -- @tparam[opt=false] boolean tasklist_disable_task_name
 
@@ -171,6 +203,8 @@ local instances
 --
 -- See the <a href="#status_icons">Status icons</a> section for more details.
 --
+-- @DOC_wibox_awidget_tasklist_style_plain_task_name_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_plain_task_name
 -- @tparam[opt=false] boolean tasklist_plain_task_name
 
@@ -210,110 +244,178 @@ local instances
 -- @beautiful beautiful.tasklist_minimized
 -- @tparam[opt=nil] string minimized
 
+--- The focused client alignment.
+--
+-- @DOC_wibox_awidget_tasklist_style_align_EXAMPLE@
+--
+-- @beautiful beautiful.tasklist_align
+-- @tparam[opt="left"] string align *left*, *right* or *center*
+
 --- The tasklist font.
+--
+-- @DOC_wibox_awidget_tasklist_style_font_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_font
 -- @tparam[opt=nil] string font
-
---- The focused client alignment.
--- @beautiful beautiful.tasklist_align
--- @tparam[opt=left] string align *left*, *right* or *center*
+-- @see wibox.widget.textbox.font
 
 --- The focused client title alignment.
+--
+-- @DOC_wibox_awidget_tasklist_style_font_focus_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_font_focus
 -- @tparam[opt=nil] string font_focus
+-- @see wibox.widget.textbox.font
 
 --- The minimized clients font.
+--
+-- @DOC_wibox_awidget_tasklist_style_font_minimized_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_font_minimized
 -- @tparam[opt=nil] string font_minimized
+-- @see wibox.widget.textbox.font
 
 --- The urgent clients font.
+--
+-- @DOC_wibox_awidget_tasklist_style_font_urgent_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_font_urgent
 -- @tparam[opt=nil] string font_urgent
+-- @see wibox.widget.textbox.font
 
 --- The space between the tasklist elements.
+--
+-- @DOC_wibox_awidget_tasklist_style_spacing_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_spacing
 -- @tparam[opt=0] number spacing The spacing between tasks.
 
 --- The default tasklist elements shape.
+--
+-- @DOC_wibox_awidget_tasklist_style_shape_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_shape
 -- @tparam[opt=nil] gears.shape shape
 
 --- The default tasklist elements border width.
+--
+-- @DOC_wibox_awidget_tasklist_style_shape_border_width_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_shape_border_width
 -- @tparam[opt=0] number shape_border_width
 
 --- The default tasklist elements border color.
+--
+-- @DOC_wibox_awidget_tasklist_style_shape_border_color_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_shape_border_color
 -- @tparam[opt=nil] string|color shape_border_color
 -- @see gears.color
 
 --- The focused client shape.
+--
+-- @DOC_wibox_awidget_tasklist_style_shape_focus_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_shape_focus
 -- @tparam[opt=nil] gears.shape shape_focus
 
 --- The focused client border width.
+--
+-- @DOC_wibox_awidget_tasklist_style_shape_focus_border_width_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_shape_border_width_focus
 -- @tparam[opt=0] number shape_border_width_focus
 
 --- The focused client border color.
+--
+-- @DOC_wibox_awidget_tasklist_style_shape_focus_border_width_focus_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_shape_border_color_focus
 -- @tparam[opt=nil] string|color shape_border_color_focus
 -- @see gears.color
 
 --- The minimized clients shape.
+--
+-- @DOC_wibox_awidget_tasklist_style_shape_minimized_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_shape_minimized
 -- @tparam[opt=nil] gears.shape shape_minimized
 
 --- The minimized clients border width.
+--
+-- @DOC_wibox_awidget_tasklist_style_shape_border_width_minimized_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_shape_border_width_minimized
 -- @tparam[opt=0] number shape_border_width_minimized
 
 --- The minimized clients border color.
+--
+-- @DOC_wibox_awidget_tasklist_style_shape_border_color_minimized_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_shape_border_color_minimized
 -- @tparam[opt=nil] string|color shape_border_color_minimized
 -- @see gears.color
 
 --- The urgent clients shape.
+--
+-- @DOC_wibox_awidget_tasklist_style_shape_urgent_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_shape_urgent
 -- @tparam[opt=nil] gears.shape shape_urgent
 
 --- The urgent clients border width.
+--
+-- @DOC_wibox_awidget_tasklist_style_shape_border_width_urgent_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_shape_border_width_urgent
 -- @tparam[opt=0] number shape_border_width_urgent
 
 --- The urgent clients border color.
+--
+-- @DOC_wibox_awidget_tasklist_style_shape_border_color_urgent_EXAMPLE@
+--
 -- @beautiful beautiful.tasklist_shape_border_color_urgent
 -- @tparam[opt=nil] string|color shape_border_color_urgent
 -- @see gears.color
 
+--- The icon size.
+-- @beautiful beautiful.tasklist_icon_size
+-- @tparam[opt=nil] integer tasklist_icon_size
+
 -- Public structures
 tasklist.filter, tasklist.source = {}, {}
 
 -- This is the same template as awful.widget.common, but with an clienticon widget
-local default_template = {
-    {
-        {
-            clienticon,
-            id     = "icon_margin_role",
-            left   = dpi(4),
-            widget = wmargin
-        },
+local function default_template(self)
+    local has_no_icon = self._private.style.disable_icon
+        or self._private.style.tasklist_disable_icon
+        or beautiful.tasklist_disable_icon
+
+    return {
         {
+            (not has_no_icon) and {
+                clienticon,
+                id     = "icon_margin_role",
+                left   = dpi(4),
+                widget = wmargin
+            } or nil,
             {
-                id     = "text_role",
-                widget = wtextbox,
+                {
+                    id     = "text_role",
+                    widget = wtextbox,
+                },
+                id     = "text_margin_role",
+                left   = dpi(4),
+                right  = dpi(4),
+                widget = wmargin
             },
-            id     = "text_margin_role",
-            left   = dpi(4),
-            right  = dpi(4),
-            widget = wmargin
+            fill_space = true,
+            layout     = wfixed.horizontal
         },
-        fill_space = true,
-        layout     = wfixed.horizontal
-    },
-    id     = "background_role",
-    widget = wbackground
-}
+        id     = "background_role",
+        widget = wbackground
+    }
+end
 
 local function tasklist_label(c, args, tb)
     if not args then args = {} end
@@ -334,12 +436,13 @@ local function tasklist_label(c, args, tb)
     local bg_image_focus = args.bg_image_focus or theme.tasklist_bg_image_focus or theme.bg_image_focus
     local bg_image_urgent = args.bg_image_urgent or theme.tasklist_bg_image_urgent or theme.bg_image_urgent
     local bg_image_minimize = args.bg_image_minimize or theme.tasklist_bg_image_minimize or theme.bg_image_minimize
-    local tasklist_disable_icon = args.tasklist_disable_icon or theme.tasklist_disable_icon or false
+    local tasklist_disable_icon = args.disable_icon or args.tasklist_disable_icon
+        or theme.tasklist_disable_icon or false
     local disable_task_name = args.disable_task_name or theme.tasklist_disable_task_name or false
-    local font = args.font or theme.tasklist_font or theme.font or ""
-    local font_focus = args.font_focus or theme.tasklist_font_focus or theme.font_focus or font or ""
-    local font_minimized = args.font_minimized or theme.tasklist_font_minimized or theme.font_minimized or font or ""
-    local font_urgent = args.font_urgent or theme.tasklist_font_urgent or theme.font_urgent or font or ""
+    local font = args.font or theme.tasklist_font or theme.font
+    local font_focus = args.font_focus or theme.tasklist_font_focus or theme.font_focus or font
+    local font_minimized = args.font_minimized or theme.tasklist_font_minimized or theme.font_minimized or font
+    local font_urgent = args.font_urgent or theme.tasklist_font_urgent or theme.font_urgent or font
     local text = ""
     local name = ""
     local bg
@@ -476,10 +579,10 @@ local function create_callback(w, t)
     common._set_common_property(w, "client", t)
 end
 
-local function tasklist_update(s, w, buttons, filter, data, style, update_function, args)
+local function tasklist_update(s, self, buttons, filter, data, style, update_function, args)
     local clients = {}
 
-    local source = args and args.source or tasklist.source.all_clients or nil
+    local source = self.source or tasklist.source.all_clients or nil
     local list   = source and source(s, args) or capi.client.get()
 
     for _, c in ipairs(list) do
@@ -490,14 +593,219 @@ local function tasklist_update(s, w, buttons, filter, data, style, update_functi
         end
     end
 
+    if self._private.last_count ~= #clients then
+        local old = self._private.last_count
+        self._private.last_count = #clients
+        self:emit_signal("property::count", #clients, old)
+    end
+
     local function label(c, tb) return tasklist_label(c, style, tb) end
 
-    update_function(w, buttons, label, data, clients, {
-        widget_template = args.widget_template or default_template,
+    update_function(self._private.base_layout, buttons, label, data, clients, {
+        widget_template = self._private.widget_template or default_template(self),
         create_callback = create_callback,
     })
 end
 
+--- The current number of clients.
+--
+-- Note that the `tasklist` is usually lazy-loaded. Reading this property
+-- may cause the widgets to be created. Depending on where the property is called
+-- from, it might, in theory, cause an infinite loop.
+--
+-- @property count
+-- @readonly
+-- @tparam number count
+-- @propertydefault The current number of client.
+-- @negativeallowed false
+-- @propemits true false
+
+--- Set the tasklist layout.
+--
+-- This can be used to change the layout based on the number of clients:
+--
+-- @DOC_sequences_client_tasklist_layout1_EXAMPLE@
+--
+-- @property base_layout
+-- @tparam[opt=wibox.layout.flex.horizontal] wibox.layout base_layout
+-- @propemits true false
+-- @see wibox.layout.flex.horizontal
+
+--- The tasklist screen.
+--
+-- @DOC_sequences_client_tasklist_screen1_EXAMPLE@
+--
+-- @property screen
+-- @tparam screen screen
+-- @propertydefault Obtained from the constructor.
+-- @propemits true false
+
+--- A function to narrow down the list of clients.
+--
+-- @DOC_sequences_client_tasklist_custom_filter1_EXAMPLE@
+--
+-- @property filter
+-- @tparam[opt=awful.widget.tasklist.filter.alltags] function filter
+-- @functionparam client c The client to accept or reject.
+-- @functionparam screen s The value of the tasklist `screen` property.
+-- @functionreturn boolean `true` if the client is accepter or `false` if it is rejected.
+-- @propemits true false
+-- @see awful.widget.tasklist.filter.allscreen
+-- @see awful.widget.tasklist.filter.alltags
+-- @see awful.widget.tasklist.filter.currenttags
+-- @see awful.widget.tasklist.filter.minimizedcurrenttags
+-- @see awful.widget.tasklist.filter.focused
+
+--- A function called when the tasklist is refreshed.
+--
+-- This is a very low level API, prefer `widget_template` whenever
+-- you can.
+--
+-- @property update_function
+-- @tparam function|nil update_function
+-- @propertydefault The default function delegate everything to the `widget_template`.
+-- @functionparam widget layout The base layout object.
+-- @functionparam table buttons The buttons for this client entry (see below).
+-- @functionparam string label The client name.
+-- @functionparam table data Arbitrary metadate.
+-- @functionparam table clients The list of clients (ordered).
+-- @functionparam table metadata Other values.
+-- @functionnoreturn
+-- @propemits true false
+
+--- A template for creating the client widgets.
+--
+-- @DOC_sequences_client_tasklist_widget_template1_EXAMPLE@
+--
+-- @property widget_template
+-- @tparam[opt=nil] template|nil widget_template
+-- @propemits true false
+
+--- A function to gather the clients to display.
+--
+-- @DOC_sequences_client_tasklist_custom_source1_EXAMPLE@
+--
+-- @property source
+-- @tparam[opt=awful.widget.tasklist.source.all_clients] function source
+-- @functionparam screen s The tasklist screen.
+-- @functionparam table metadata Various metadata.
+-- @functionreturn table The list of clients.
+-- @propemits true false
+-- @see awful.widget.tasklist.source.all_clients
+
+function tasklist:set_base_layout(layout)
+    self._private.base_layout = base.make_widget_from_value(
+        layout or flex.horizontal
+    )
+
+    local spacing = self._private.style.spacing or beautiful.tasklist_spacing
+
+    if self._private.base_layout.set_spacing and spacing then
+        self._private.base_layout:set_spacing(spacing)
+    end
+
+    assert(self._private.base_layout.is_widget)
+
+    self._do_tasklist_update()
+
+    self:emit_signal("widget::layout_changed")
+    self:emit_signal("widget::redraw_needed")
+    self:emit_signal("property::base_layout", layout)
+end
+
+function tasklist:get_count()
+    if not self._private.last_count then
+        self._do_tasklist_update_now()
+    end
+
+    return self._private.last_count
+end
+
+function tasklist:layout(_, width, height)
+    if self._private.base_layout then
+        return { base.place_widget_at(self._private.base_layout, 0, 0, width, height) }
+    end
+end
+
+function tasklist:fit(context, width, height)
+    if not self._private.base_layout then
+        return 0, 0
+    end
+
+    return base.fit_widget(self, context, self._private.base_layout, width, height)
+end
+
+for _, prop in ipairs { "screen", "filter", "update_function", "widget_template", "source"} do
+    tasklist["set_"..prop] = function(self, value)
+        if value == self._private[prop] then return end
+
+        self._private[prop] = value
+
+        self._do_tasklist_update()
+
+        self:emit_signal("widget::layout_changed")
+        self:emit_signal("widget::redraw_needed")
+        self:emit_signal("property::"..prop, value)
+    end
+
+    tasklist["get_"..prop] = function(self)
+        return self._private[prop]
+    end
+end
+
+local function update_screen(self, screen, old)
+    if not instances then return end
+
+    if old and instances[old] then
+        for k, w in ipairs(instances[old]) do
+            if w == self then
+                table.remove(instances[old], k)
+                break
+            end
+        end
+    end
+
+    local list = instances[screen]
+
+    if not list then
+        list = setmetatable({}, { __mode = "v" })
+        instances[screen] = list
+    end
+
+    table.insert(list, self)
+end
+
+function tasklist:set_screen(value)
+    value = get_screen(value)
+
+    if value == self._private.screen then return end
+
+    local old = self._private.screen
+
+    self._private.screen = value
+
+    update_screen(self, screen, old)
+
+    self._do_tasklist_update()
+
+    self:emit_signal("widget::layout_changed")
+    self:emit_signal("widget::redraw_needed")
+    self:emit_signal("property::screen", value)
+end
+
+function tasklist:set_widget_template(widget_template)
+    self._private.widget_template = widget_template
+
+    -- Remove the existing instances
+    self._private.data = setmetatable({}, { __mode = 'k' })
+
+    self._do_tasklist_update()
+
+    self:emit_signal("widget::layout_changed")
+    self:emit_signal("widget::redraw_needed")
+    self:emit_signal("property::widget_template", widget_template)
+end
+
 --- Create a new tasklist widget.
 -- The last two arguments (update_function
 -- and layout) serve to customize the layout of the tasklist (eg. to
@@ -518,53 +826,58 @@ end
 --  function used to generate the list of client.
 -- @tparam[opt] table args.widget_template A custom widget to be used for each client
 -- @tparam[opt={}] table args.style The style overrides default theme.
--- @tparam[opt=nil] string|pattern args.style.fg_normal
--- @tparam[opt=nil] string|pattern args.style.bg_normal
--- @tparam[opt=nil] string|pattern args.style.fg_focus
--- @tparam[opt=nil] string|pattern args.style.bg_focus
--- @tparam[opt=nil] string|pattern args.style.fg_urgent
--- @tparam[opt=nil] string|pattern args.style.bg_urgent
--- @tparam[opt=nil] string|pattern args.style.fg_minimize
--- @tparam[opt=nil] string|pattern args.style.bg_minimize
--- @tparam[opt=nil] string args.style.bg_image_normal
--- @tparam[opt=nil] string args.style.bg_image_focus
--- @tparam[opt=nil] string args.style.bg_image_urgent
--- @tparam[opt=nil] string args.style.bg_image_minimize
--- @tparam[opt=nil] boolean args.style.tasklist_disable_icon
--- @tparam[opt=nil] number args.style.icon_size The size of the icon
--- @tparam[opt='▪'] string args.style.sticky Extra icon when client is sticky
--- @tparam[opt='⌃'] string args.style.ontop Extra icon when client is ontop
--- @tparam[opt='▴'] string args.style.above Extra icon when client is above
--- @tparam[opt='▾'] string args.style.below Extra icon when client is below
--- @tparam[opt='✈'] string args.style.floating Extra icon when client is floating
--- @tparam[opt='<b>+</b>'] string args.style.maximized Extra icon when client is maximized
--- @tparam[opt='⬌'] string args.style.maximized_horizontal Extra icon when client is maximized_horizontal
--- @tparam[opt='⬍'] string args.style.maximized_vertical Extra icon when client is maximized_vertical
--- @tparam[opt=false] boolean args.style.disable_task_name
--- @tparam[opt=nil] string args.style.font
--- @tparam[opt=left] string args.style.align *left*, *right* or *center*
--- @tparam[opt=nil] string args.style.font_focus
--- @tparam[opt=nil] string args.style.font_minimized
--- @tparam[opt=nil] string args.style.font_urgent
--- @tparam[opt=nil] number args.style.spacing The spacing between tags.
--- @tparam[opt=nil] gears.shape args.style.shape
--- @tparam[opt=nil] number args.style.shape_border_width
--- @tparam[opt=nil] string|color args.style.shape_border_color
--- @tparam[opt=nil] gears.shape args.style.shape_focus
--- @tparam[opt=nil] number args.style.shape_border_width_focus
--- @tparam[opt=nil] string|color args.style.shape_border_color_focus
--- @tparam[opt=nil] gears.shape args.style.shape_minimized
--- @tparam[opt=nil] number args.style.shape_border_width_minimized
--- @tparam[opt=nil] string|color args.style.shape_border_color_minimized
--- @tparam[opt=nil] gears.shape args.style.shape_urgent
--- @tparam[opt=nil] number args.style.shape_border_width_urgent
--- @tparam[opt=nil] string|color args.style.shape_border_color_urgent
+-- @tparam[opt=beautiful.tasklist_fg_normal] string|pattern args.style.fg_normal
+-- @tparam[opt=beautiful.tasklist_bg_normal] string|pattern args.style.bg_normal
+-- @tparam[opt=beautiful.tasklist_fg_focus or beautiful.fg_focus] string|pattern args.style.fg_focus
+-- @tparam[opt=beautiful.tasklist_bg_focus or beautiful.bg_focus] string|pattern args.style.bg_focus
+-- @tparam[opt=beautiful.tasklist_fg_urgent or beautiful.fg_urgent] string|pattern args.style.fg_urgent
+-- @tparam[opt=beautiful.tasklist_bg_urgent or beautiful.bg_urgent] string|pattern args.style.bg_urgent
+-- @tparam[opt=beautiful.tasklist_fg_minimize or beautiful.fg_minimize] string|pattern args.style.fg_minimize
+-- @tparam[opt=beautiful.tasklist_bg_minimize or beautiful.bg_minimize] string|pattern args.style.bg_minimize
+-- @tparam[opt=beautiful.tasklist_bg_image_normal] string args.style.bg_image_normal
+-- @tparam[opt=beautiful.tasklist_bg_image_focus] string args.style.bg_image_focus
+-- @tparam[opt=beautiful.tasklist_bg_image_urgent] string args.style.bg_image_urgent
+-- @tparam[opt=beautiful.tasklist_bg_image_minimize] string args.style.bg_image_minimize
+-- @tparam[opt=beautiful.tasklist_disable_icon] boolean args.style.disable_icon
+-- @tparam[opt=beautiful.tasklist_icon_size] number args.style.icon_size The size of the icon
+-- @tparam[opt=beautiful.tasklist_sticky or '▪'] string args.style.sticky Extra icon when client is sticky
+-- @tparam[opt=beautiful.tasklist_ontop or '⌃'] string args.style.ontop Extra icon when client is ontop
+-- @tparam[opt=beautiful.tasklist_above or '▴'] string args.style.above Extra icon when client is above
+-- @tparam[opt=beautiful.tasklist_below or '▾'] string args.style.below Extra icon when client is below
+-- @tparam[opt=beautiful.tasklist_floating or '✈'] string args.style.floating Extra icon when client is floating
+-- @tparam[opt=beautiful.tasklist_maximized or '<b>+</b>'] string args.style.maximized Extra
+--   icon when client is maximized
+-- @tparam[opt=beautiful.tasklist_maximized_horizontal or '⬌'] string args.style.maximized_horizontal Extra
+--   icon when client is maximized_horizontal
+-- @tparam[opt=beautiful.tasklist_maximized_vertical or '⬍'] string args.style.maximized_vertical Extra
+--   icon when client is maximized_vertical
+-- @tparam[opt=beautiful.tasklist_disable_task_name or false] boolean args.style.disable_task_name
+-- @tparam[opt=beautiful.tasklist_font] string args.style.font
+-- @tparam[opt=beautiful.tasklist_align or "left"] string args.style.align *left*, *right* or *center*
+-- @tparam[opt=beautiful.tasklist_font_focus] string args.style.font_focus
+-- @tparam[opt=beautiful.tasklist_font_minimized] string args.style.font_minimized
+-- @tparam[opt=beautiful.tasklist_font_urgent] string args.style.font_urgent
+-- @tparam[opt=beautiful.tasklist_spacing] number args.style.spacing The spacing between tags.
+-- @tparam[opt=beautiful.tasklist_shape] gears.shape args.style.shape
+-- @tparam[opt=beautiful.tasklist_shape_border_width] number args.style.shape_border_width
+-- @tparam[opt=beautiful.tasklist_shape_border_color] string|color args.style.shape_border_color
+-- @tparam[opt=beautiful.tasklist_shape_focus] gears.shape args.style.shape_focus
+-- @tparam[opt=beautiful.tasklist_shape_border_width_focus] number args.style.shape_border_width_focus
+-- @tparam[opt=beautiful.tasklist_shape_border_color_focus] string|color args.style.shape_border_color_focus
+-- @tparam[opt=beautiful.tasklist_shape_minimized] gears.shape args.style.shape_minimized
+-- @tparam[opt=beautiful.tasklist_shape_border_width_minimized] number args.style.shape_border_width_minimized
+-- @tparam[opt=beautiful.tasklist_shape_border_color_minimized] string|color args.style.shape_border_color_minimized
+-- @tparam[opt=beautiful.tasklist_shape_urgent] gears.shape args.style.shape_urgent
+-- @tparam[opt=beautiful.tasklist_shape_border_width_urgent] number args.style.shape_border_width_urgent
+-- @tparam[opt=beautiful.tasklist_shape_border_color_urgent] string|color args.style.shape_border_color_urgent
+-- @tparam[opt=beautiful.tasklist_minimized ] string|color args.style.minimized
 -- @param filter **DEPRECATED** use args.filter
 -- @param buttons **DEPRECATED** use args.buttons
 -- @param style **DEPRECATED** use args.style
 -- @param update_function **DEPRECATED** use args.update_function
--- @param base_widget **DEPRECATED** use args.base_widget
+-- @param base_widget **DEPRECATED** use args.base_layout
 -- @constructorfct awful.widget.tasklist
+-- @usebeautiful beautiful.tasklist_plain_task_name
 function tasklist.new(args, filter, buttons, style, update_function, base_widget)
     local screen = nil
 
@@ -596,23 +909,37 @@ function tasklist.new(args, filter, buttons, style, update_function, base_widget
 
     screen = screen or get_screen(args.screen)
     local uf = args.update_function or common.list_update
-    local w = base.make_widget_from_value(args.layout or flex.horizontal)
 
-    local data = setmetatable({}, { __mode = 'k' })
+    local w = base.make_widget(nil, nil, {
+        enable_properties = true,
+    })
 
-    local spacing = args.style and args.style.spacing or args.layout and args.layout.spacing
-                    or beautiful.tasklist_spacing
-    if w.set_spacing and spacing then
-        w:set_spacing(spacing)
-    end
+    gtable.crush(w._private, {
+        disable_task_name = args.disable_task_name,
+        disable_icon      = args.disable_icon,
+        update_function   = args.update_function,
+        filter            = args.filter,
+        buttons           = args.buttons,
+        style             = args.style or {},
+        screen            = screen,
+        widget_template   = args.widget_template,
+        source            = args.source,
+        data              = setmetatable({}, { __mode = 'k' })
+    })
+
+    gtable.crush(w, tasklist, true)
+    rawset(w, "filter", nil)
+    rawset(w, "source", nil)
 
     local queued_update = false
 
     -- For the tests
     function w._do_tasklist_update_now()
         queued_update = false
-        if screen.valid then
-            tasklist_update(screen, w, args.buttons, args.filter, data, args.style, uf, args)
+        if w._private.screen.valid then
+            tasklist_update(
+                w._private.screen, w, w._private.buttons, w._private.filter, w._private.data, args.style, uf, args
+            )
         end
     end
 
@@ -624,7 +951,7 @@ function tasklist.new(args, filter, buttons, style, update_function, base_widget
         end
     end
     function w._unmanage(c)
-        data[c] = nil
+        w._private.data[c] = nil
     end
     if instances == nil then
         instances = setmetatable({}, { __mode = "k" })
@@ -681,17 +1008,20 @@ function tasklist.new(args, filter, buttons, style, update_function, base_widget
             instances[get_screen(s)] = nil
         end)
     end
+
+    tasklist.set_base_layout(w, args.layout or args.base_layout)
+
     w._do_tasklist_update()
-    local list = instances[screen]
-    if not list then
-        list = setmetatable({}, { __mode = "v" })
-        instances[screen] = list
-    end
-    table.insert(list, w)
+
+    update_screen(w, screen)
+
     return w
 end
 
 --- Filtering function to include all clients.
+--
+--@DOC_sequences_client_tasklist_filter_allscreen1_EXAMPLE@
+--
 -- @return true
 -- @filterfunction awful.widget.tasklist.filter.allscreen
 function tasklist.filter.allscreen()
@@ -699,8 +1029,11 @@ function tasklist.filter.allscreen()
 end
 
 --- Filtering function to include the clients from all tags on the screen.
--- @param c The client.
--- @param screen The screen we are drawing on.
+--
+--@DOC_sequences_client_tasklist_filter_alltags1_EXAMPLE@
+--
+-- @tparam client c The client.
+-- @tparam screen screen The screen we are drawing on.
 -- @return true if c is on screen, false otherwise
 -- @filterfunction awful.widget.tasklist.filter.alltags
 function tasklist.filter.alltags(c, screen)
@@ -709,8 +1042,13 @@ function tasklist.filter.alltags(c, screen)
 end
 
 --- Filtering function to include only the clients from currently selected tags.
--- @param c The client.
--- @param screen The screen we are drawing on.
+--
+-- This is the filter used in the default `rc.lua`.
+--
+--@DOC_sequences_client_tasklist_filter_currenttags1_EXAMPLE@
+--
+-- @tparam client c The client.
+-- @tparam screen screen The screen we are drawing on.
 -- @return true if c is in a selected tag on screen, false otherwise
 -- @filterfunction awful.widget.tasklist.filter.currenttags
 function tasklist.filter.currenttags(c, screen)
@@ -734,8 +1072,11 @@ function tasklist.filter.currenttags(c, screen)
 end
 
 --- Filtering function to include only the minimized clients from currently selected tags.
--- @param c The client.
--- @param screen The screen we are drawing on.
+--
+--@DOC_sequences_client_tasklist_filter_minimizedcurrenttags1_EXAMPLE@
+--
+-- @tparam client c The client.
+-- @tparam screen screen The screen we are drawing on.
 -- @return true if c is in a selected tag on screen and is minimized, false otherwise
 -- @filterfunction awful.widget.tasklist.filter.minimizedcurrenttags
 function tasklist.filter.minimizedcurrenttags(c, screen)
@@ -762,8 +1103,11 @@ function tasklist.filter.minimizedcurrenttags(c, screen)
 end
 
 --- Filtering function to include only the currently focused client.
--- @param c The client.
--- @param screen The screen we are drawing on.
+--
+--@DOC_sequences_client_tasklist_filter_focused1_EXAMPLE@
+--
+-- @tparam client c The client.
+-- @tparam screen screen The screen we are drawing on.
 -- @return true if c is focused on screen, false otherwise
 -- @filterfunction awful.widget.tasklist.filter.focused
 function tasklist.filter.focused(c, screen)
@@ -784,8 +1128,6 @@ function tasklist.mt:__call(...)
     return tasklist.new(...)
 end
 
---@DOC_widget_COMMON@
-
 --@DOC_object_COMMON@
 
 return setmetatable(tasklist, tasklist.mt)

lib/awful/widget/watch.lua

@@ -1,5 +1,6 @@
 ---------------------------------------------------------------------------
---- Watch widget.
+--- Execute a command at a set interval and display its output.
+--
 -- Here is an example of simple temperature widget which will update each 15
 -- seconds implemented in two different ways.
 -- The first, simpler one, will just display the return command output
@@ -7,20 +8,18 @@
 -- In the other example `sensors` returns to the widget its full output
 -- and it's trimmed in the widget callback function:
 --
---     211             mytextclock,
---     212             wibox.widget.textbox('  |  '),
---     213             -- one way to do that:
---     214             awful.widget.watch('bash -c "sensors | grep temp1"', 15),
---     215             -- another way:
---     216             awful.widget.watch('sensors', 15, function(widget, stdout)
---     217               for line in stdout:gmatch("[^\r\n]+") do
---     218                 if line:match("temp1") then
---     219                   widget:set_text(line)
---     220                   return
---     221                 end
---     222               end
---     223             end),
---     224             s.mylayoutbox,
+--    -- one way to do that:
+--    local w = awful.widget.watch('bash -c "sensors | grep temp1"', 15)
+--
+--    -- another way:
+--    local w = awful.widget.watch('sensors', 15, function(widget, stdout)
+--        for line in stdout:gmatch("[^\r\n]+") do
+--            if line:match("temp1") then
+--                widget:set_text(line)
+--                return
+--            end
+--        end
+--    end)
 --
 -- ![Example screenshot](../images/awful_widget_watch.png)
 --
@@ -32,6 +31,7 @@
 -- @author Yauheni Kirylau
 -- @copyright 2015, 2016 Benjamin Petrenko, Yauheni Kirylau
 -- @widgetmod awful.widget.watch
+-- @supermodule wibox.widget.base
 ---------------------------------------------------------------------------
 
 local setmetatable = setmetatable
@@ -55,7 +55,7 @@ local watch = { mt = {} }
 --     function(widget, stdout, stderr, exitreason, exitcode)
 --         widget:set_text(stdout)
 --     end
--- @param callback.widget Base widget instance.
+-- @tparam wibox.widget callback.widget Base widget instance.
 -- @tparam string callback.stdout Output on stdout.
 -- @tparam string callback.stderr Output on stderr.
 -- @tparam string callback.exitreason Exit Reason.
@@ -64,7 +64,7 @@ local watch = { mt = {} }
 -- For "exit" reason it's the exit code.
 -- For "signal" reason — the signal causing process termination.
 --
--- @param[opt=wibox.widget.textbox()] base_widget Base widget.
+-- @tparam[opt=wibox.widget.textbox()] wibox.widget base_widget Base widget.
 --
 -- @return The widget used by this watch.
 -- @return Its gears.timer.
@@ -92,8 +92,6 @@ function watch.mt.__call(_, ...)
     return watch.new(...)
 end
 
---@DOC_widget_COMMON@
-
 --@DOC_object_COMMON@
 
 return setmetatable(watch, watch.mt)

lib/beautiful/init.lua

@@ -1,5 +1,5 @@
 ----------------------------------------------------------------------------
---- Theme library.
+--- Key+value based theme library and associated utility modules.
 --
 -- @author Damien Leone <damien.leone@gmail.com>
 -- @author Julien Danjou <julien@danjou.info>
@@ -89,62 +89,52 @@ local active_font
 
 --- The default font.
 -- @beautiful beautiful.font
--- @param string
+-- @param[opt="sans 8"] string
 
--- The default background color.
+--- The default background color.
+--
+-- The background color can be transparent. If there is a
+-- compositing manager such as compton, then it will be
+-- real transparency and may include blur (provided by the
+-- compositor). When there is no compositor, it will take
+-- a picture of the wallpaper and blend it.
+--
 -- @beautiful beautiful.bg_normal
 -- @param color
 
--- The default focused element background color.
+--- The default focused element background color.
 -- @beautiful beautiful.bg_focus
 -- @param color
 
--- The default urgent element background color.
+--- The default urgent element background color.
 -- @beautiful beautiful.bg_urgent
 -- @param color
 
--- The default minimized element background color.
+--- The default minimized element background color.
 -- @beautiful beautiful.bg_minimize
 -- @param color
 
--- The system tray background color.
--- Please note that only solid colors are currently supported.
--- @beautiful beautiful.bg_systray
--- @param color
-
--- The default focused element foreground (text) color.
+--- The default focused element foreground (text) color.
 -- @beautiful beautiful.fg_normal
 -- @param color
 
--- The default focused element foreground (text) color.
+--- The default focused element foreground (text) color.
 -- @beautiful beautiful.fg_focus
 -- @param color
 
--- The default urgent element foreground (text) color.
+--- The default urgent element foreground (text) color.
 -- @beautiful beautiful.fg_urgent
 -- @param color
 
--- The default minimized element foreground (text) color.
+--- The default minimized element foreground (text) color.
 -- @beautiful beautiful.fg_minimize
 -- @param color
 
---- The gap between clients.
--- @beautiful beautiful.useless_gap
--- @param[opt=0] number
-
---- The fallback border width.
--- @beautiful beautiful.border_width
--- @param number
-
---- The fallback border color.
--- @beautiful beautiful.border_color
--- @param color
-
 --- The wallpaper path.
 -- @beautiful beautiful.wallpaper
 -- @tparam string|gears.surface wallpaper
 
--- The icon theme name.
+--- The icon theme name.
 -- It has to be a directory in `/usr/share/icons` or an XDG icon folder.
 -- @beautiful beautiful.icon_theme
 -- @param string
@@ -234,7 +224,8 @@ end
 
 --- Get the height of a font.
 --
--- @param name Name of the font.
+-- @tparam string name Name of the font.
+-- @treturn number The font height.
 -- @staticfct beautiful.get_font_height
 function beautiful.get_font_height(name)
     return load_font(name).height

lib/beautiful/theme_assets.lua

@@ -86,6 +86,7 @@ end
 -- @tparam color bg Background color.
 -- @tparam color fg Main foreground color.
 -- @tparam color alt_fg Accent foreground color.
+-- @noreturn
 -- @staticfct beautiful.theme_assets.gen_awesome_name
 function theme_assets.gen_awesome_name(cr, height, bg, fg, alt_fg)
     local ls = height/10 -- letter_size
@@ -155,6 +156,7 @@ end
 -- @tparam number height Height.
 -- @tparam color bg Background color.
 -- @tparam color fg Foreground color.
+-- @noreturn
 -- @staticfct beautiful.theme_assets.gen_logo
 function theme_assets.gen_logo(cr, width, height, bg, fg)
     local ls = math.min(width, height)

lib/beautiful/xresources.lua

@@ -119,6 +119,7 @@ end
 --- Set DPI for a given screen (defaults to global).
 -- @tparam number dpi DPI value.
 -- @tparam[opt] integer s Screen.
+-- @noreturn
 -- @staticfct beautiful.xresources.set_dpi
 function xresources.set_dpi(dpi, s)
     s = get_screen(s)

lib/gears/color.lua

@@ -53,6 +53,7 @@ local surface = require("gears.surface")
 
 local color = { mt = {} }
 local pattern_cache
+local color_string_cache = setmetatable({}, { __mode = "k" })
 
 --- Parse a HTML-color.
 -- This function can parse colors like `#rrggbb` and `#rrggbbaa` and also `red`.
@@ -281,6 +282,7 @@ end
 
 --- Create a pattern from a given string, same as @{gears.color}.
 -- @see gears.color
+-- @treturn gears.color A cairo pattern object.
 -- @staticfct gears.color.create_pattern
 function color.create_pattern(col)
     if cairo.Pattern:is_type_of(col) then
@@ -354,12 +356,75 @@ function color.recolor_image(image, new_color)
     return image
 end
 
+--- Take an input color and set a different opacity.
+--
+-- @staticfct gears.color.change_opacity
+-- @tparam string|pattern input The input color.
+-- @tparam number opacity A floating point number between 0 and 1.
+-- @treturn color The new color if successful or `input` if invalid.
+function color.change_opacity(input, opacity)
+    input = color.create_pattern(input)
+
+    local error, r, g, b, _ = input:get_rgba()
+
+    if error ~= "SUCCESS" then return input end
+
+    return cairo.Pattern.create_rgba(r, g, b, opacity)
+end
+
+--- Convert a color back to an hexadecimal color code.
+--
+-- This takes an input color, pattern or gradient and attempt to convert it
+-- to a color. If this fails, `fallback` is returned. This is useful when a
+-- color needs to be concatenated into a Pango markup string.
+--
+-- @staticfct gears.color.to_rgba_string
+-- @tparam pattern|string|gradient color Note that only solid colors can be
+--  convedted to the `RGBA` format.
+-- @tparam[opt=nil]  pattern|string|gradient fallback The color to return
+--  if `color` cannot be converted to a string.
+-- @treturn string The color in `#rrggbbaa` format.
+-- @see gears.color.ensure_pango_color
+
+function color.to_rgba_string(col, fallback)
+    if (not col) and (not fallback) then return nil end
+
+    -- Prevent infinite recursion.
+    if not col then return color.to_rgba_string(fallback) end
+
+    if color_string_cache[col] then
+        return color_string_cache[col]
+    end
+
+    col = color.create_pattern(col)
+
+    local error1, error2, r, g, b, a = pcall(function () return col:get_rgba() end)
+
+    -- Surface patterns don't have an RGBA representation.
+    if (not error1) or error2 ~= "SUCCESS" then return color.to_rgba_string(fallback) end
+
+    color_string_cache[col] = string.format(
+        "#%02x%02x%02x%02x",
+        math.floor(r*255),
+        math.floor(g*255),
+        math.floor(b*255),
+        math.floor(a*255)
+    )
+
+    return color_string_cache[col]
+end
+
 --- Get a valid color for Pango markup
 -- @param check_color The color to check.
 -- @tparam string fallback The color to return if the first is invalid. (default: black)
 -- @treturn string color if it is valid, else fallback.
 -- @staticfct gears.color.ensure_pango_color
 function color.ensure_pango_color(check_color, fallback)
+    -- This will happen if `gears.color` has been called in the theme.
+    if type(check_color) == "userdata" then
+        return color.to_rgba_string(check_color, fallback)
+    end
+
     check_color = tostring(check_color)
     -- Pango markup supports alpha, PangoColor does not. Thus, check for this.
     local len = #check_color

lib/gears/debug.lua

@@ -1,4 +1,6 @@
 ---------------------------------------------------------------------------
+-- Utility functions to make development easier.
+--
 -- @author Uli Schlachter
 -- @copyright 2010 Uli Schlachter
 -- @utillib gears.debug
@@ -48,7 +50,7 @@ end
 -- @param data Value to inspect.
 -- @param tag The name of the value.
 -- @tparam[opt] int depth Depth of recursion.
--- @return string A string that contains the expanded value of data.
+-- @treturn string A string that contains the expanded value of data.
 -- @staticfct gears.debug.dump_return
 function debug.dump_return(data, tag, depth)
     return dump_raw(data, nil, tag, depth)
@@ -59,6 +61,7 @@ end
 -- @param tag The name of the table.
 -- @tparam[opt] int depth Depth of recursion.
 -- @staticfct gears.debug.dump
+-- @noreturn
 function debug.dump(data, tag, depth)
     print(debug.dump_return(data, tag, depth))
 end
@@ -66,6 +69,7 @@ end
 --- Print an warning message
 -- @tparam string message The warning message to print.
 -- @staticfct gears.debug.print_warning
+-- @noreturn
 function debug.print_warning(message)
     io.stderr:write(os.date("%Y-%m-%d %T W: awesome: ") .. tostring(message) .. "\n")
 end
@@ -73,6 +77,7 @@ end
 --- Print an error message
 -- @tparam string message The error message to print.
 -- @staticfct gears.debug.print_error
+-- @noreturn
 function debug.print_error(message)
     io.stderr:write(os.date("%Y-%m-%d %T E: awesome: ") .. tostring(message) .. "\n")
 end
@@ -91,6 +96,7 @@ local displayed_deprecations = {}
 -- @tparam integer args.deprecated_in Print the message only when Awesome's
 --   version is equal to or greater than deprecated_in.
 -- @staticfct gears.debug.deprecate
+-- @noreturn
 -- @emits debug::deprecation This is usually routed to stdout when the API is
 --  newly deprecated.
 -- @emitstparam debug::deprecation string msg The full formatted message.
@@ -141,7 +147,7 @@ end
 -- @tparam table fallback The new class.
 -- @tparam string old_name The old class name.
 -- @tparam string new_name The new class name.
--- @tparam[opt={}] args The name.
+-- @tparam[opt={}] table args The name.
 -- @tparam[opt] number args.deprecated_in The version which deprecated this
 --  class.
 -- @treturn table A proxy class.

lib/gears/filesystem.lua

@@ -1,5 +1,8 @@
 ---------------------------------------------------------------------------
---- Filesystem module for gears.
+--- Various filesystem utility functions.
+--
+-- Note that these functions are blocking. If you need to do a large number of
+-- I/O operations, it is better to use `lgi.Gio` async functions.
 --
 -- @utillib gears.filesystem
 ---------------------------------------------------------------------------

lib/gears/matcher.lua

@@ -225,6 +225,7 @@ end
 --  "except" and "except_any" keys. If no rules are provided, all rules
 --  registered with a source will be matched.
 -- @method matching_rules
+-- @treturn table The matching rules.
 function matcher:matching_rules(o, rules)
 
     -- Match all sources.
@@ -290,6 +291,7 @@ end
 -- @tparam string name The property name.
 -- @tparam function f The matching function.
 -- @method add_property_matcher
+-- @noreturn
 -- @usage -- Manually match the screen in various ways.
 -- matcher:add_property_matcher("screen", function(c, value)
 --    return c.screen == value
@@ -313,6 +315,7 @@ end
 -- the context of a rule.
 --
 -- @method add_property_setter
+-- @noreturn
 -- @tparam string name The property name.
 -- @tparam function f The setter function.
 function matcher:add_property_setter(name, f)
@@ -472,6 +475,7 @@ end
 --
 -- @param o The object.
 -- @method apply
+-- @noreturn
 function matcher:apply(o)
     local callbacks, props = {}, {}
     for _, v in ipairs(self._matching_source) do
@@ -514,6 +518,7 @@ end
 -- @tparam string source The source name.
 -- @tparam table rule A valid rule.
 -- @method append_rule
+-- @noreturn
 function matcher:append_rule(source, rule)
     if not self._matching_rules[source] then
         self:add_matching_rules(source, {}, {}, {})
@@ -526,6 +531,7 @@ end
 -- @tparam string source The source name.
 -- @tparam table rules A table with rules.
 -- @method append_rules
+-- @noreturn
 function matcher:append_rules(source, rules)
     for _, rule in ipairs(rules) do
         self:append_rule(source, rule)

lib/gears/math.lua

@@ -1,4 +1,6 @@
 ---------------------------------------------------------------------------
+-- Various math related functions.
+--
 --- Math module for gears.
 --
 -- @utillib gears.math

lib/gears/object.lua

@@ -52,6 +52,7 @@ end
 -- @tparam string name The name of the signal.
 -- @tparam function func The callback to call when the signal is emitted.
 -- @method connect_signal
+-- @noreturn
 function object:connect_signal(name, func)
     assert(type(func) == "function", "callback must be a function, got: " .. type(func))
     local sig = find_signal(self, name)
@@ -105,6 +106,7 @@ end
 -- @tparam string name The name of the signal.
 -- @tparam function func The callback to call when the signal is emitted.
 -- @method weak_connect_signal
+-- @noreturn
 function object:weak_connect_signal(name, func)
     assert(type(func) == "function", "callback must be a function, got: " .. type(func))
     local sig = find_signal(self, name)
@@ -116,6 +118,7 @@ end
 -- @tparam string name The name of the signal.
 -- @tparam function func The callback that should be disconnected.
 -- @method disconnect_signal
+-- @noreturn
 function object:disconnect_signal(name, func)
     local sig = find_signal(self, name)
     sig.weak[func] = nil
@@ -129,6 +132,7 @@ end
 --   function receives the object as first argument and then any extra
 --   arguments that are given to emit_signal()
 -- @method emit_signal
+-- @noreturn
 function object:emit_signal(name, ...)
     local sig = find_signal(self, name)
     for func in pairs(sig.strong) do

lib/gears/protected_call.lua

@@ -1,4 +1,9 @@
 ---------------------------------------------------------------------------
+-- Safely call a function and handle errors using `gears.debug`.
+--
+-- This is a `pcall`/`xpcall` wrapper. All it does is to integrate into the
+-- AwesomeWM-wide error handling and logging.
+--
 -- @author Uli Schlachter
 -- @copyright 2016 Uli Schlachter
 -- @utillib gears.protected_call

lib/gears/shape.lua

@@ -74,7 +74,9 @@ local module = {}
 -- @tparam boolean br If the bottom right corner is rounded
 -- @tparam boolean bl If the bottom left corner is rounded
 -- @tparam number rate The "squareness" of the squircle, should be greater than 1
--- @tparam number delta The "smoothness" of the shape, delta must be greater than 0.01 and will be reset to 0.01 if not
+-- @tparam number delta The "smoothness" of the shape, delta must be greate
+--  than 0.01 and will be reset to 0.01 if not
+-- @noreturn
 -- @staticfct gears.shape.partial_squircle
 function module.partial_squircle(cr, width, height, tl, tr, br, bl, rate, delta)
    -- rate ~ 2 can be used by icon
@@ -167,7 +169,9 @@ end
 -- @tparam number width The shape width
 -- @tparam number height The shape height
 -- @tparam number rate The "squareness" of the squircle, should be greater than 1
--- @tparam number delta The "smoothness" of the shape, delta must be greater than 0.01 and will be reset to 0.01 if not
+-- @tparam number delta The "smoothness" of the shape, delta must be greater
+--  than 0.01 and will be reset to 0.01 if not
+-- @noreturn
 -- @staticfct gears.shape.squircle
 function module.squircle(cr, width, height, rate, delta)
    module.partial_squircle(cr, width, height, true, true, true, true, rate, delta)
@@ -182,6 +186,7 @@ end
 -- @tparam number width The width constraint
 -- @tparam number height The height constraint
 -- @tparam number n Number of grams (default n = 5 -> pentagram)
+-- @noreturn
 -- @staticfct gears.shape.star
 function module.star(cr, width, height, n)
     -- use the minimum as size
@@ -215,7 +220,8 @@ end
 -- @param cr A cairo content
 -- @tparam number width The rectangle width
 -- @tparam number height The rectangle height
--- @tparam number radius the corner radius
+-- @tparam number radius The corner radius
+-- @noreturn
 -- @staticfct gears.shape.rounded_rect
 function module.rounded_rect(cr, width, height, radius)
 
@@ -246,6 +252,7 @@ end
 -- @param cr A cairo content
 -- @param width The rectangle width
 -- @param height The rectangle height.
+-- @noreturn
 -- @staticfct gears.shape.rounded_bar
 function module.rounded_bar(cr, width, height)
     module.rounded_rect(cr, width, height, height / 2)
@@ -263,6 +270,7 @@ end
 -- @tparam boolean br If the bottom right corner is rounded
 -- @tparam boolean bl If the bottom left corner is rounded
 -- @tparam number rad The corner radius
+-- @noreturn
 -- @staticfct gears.shape.partially_rounded_rect
 function module.partially_rounded_rect(cr, width, height, tl, tr, br, bl, rad)
     rad = rad or 10
@@ -319,6 +327,7 @@ end
 -- @tparam[opt=5] number corner_radius The corner radius
 -- @tparam[opt=10] number arrow_size The width and height of the arrow
 -- @tparam[opt=width/2 - arrow_size/2] number arrow_position The position of the arrow
+-- @noreturn
 -- @staticfct gears.shape.infobubble
 function module.infobubble(cr, width, height, corner_radius, arrow_size, arrow_position)
     arrow_size     = arrow_size     or 10
@@ -353,6 +362,7 @@ end
 -- @tparam number width The shape width
 -- @tparam number height The shape height
 -- @tparam[opt=height/2] number arrow_length The length of the arrow part
+-- @noreturn
 -- @staticfct gears.shape.rectangular_tag
 function module.rectangular_tag(cr, width, height, arrow_length)
     arrow_length = arrow_length or height/2
@@ -383,6 +393,7 @@ end
 -- @tparam[opt=head_width] number head_width The width of the head (/\) of the arrow
 -- @tparam[opt=width /2] number shaft_width The width of the shaft of the arrow
 -- @tparam[opt=height/2] number shaft_length The head_length of the shaft (the rest is the head)
+-- @noreturn
 -- @staticfct gears.shape.arrow
 function module.arrow(cr, width, height, head_width, shaft_width, shaft_length)
     shaft_length = shaft_length or height / 2
@@ -408,6 +419,7 @@ end
 -- @param cr A cairo context
 -- @tparam number width The shape width
 -- @tparam number height The shape height
+-- @noreturn
 -- @staticfct gears.shape.hexagon
 function module.hexagon(cr, width, height)
     cr:move_to(height/2,0)
@@ -428,6 +440,7 @@ end
 -- @tparam number width The shape width
 -- @tparam number height The shape height
 -- @tparam[opt=height/2] number arrow_depth The width of the arrow part of the shape
+-- @noreturn
 -- @staticfct gears.shape.powerline
 function module.powerline(cr, width, height, arrow_depth)
     arrow_depth = arrow_depth or height/2
@@ -456,6 +469,7 @@ end
 -- @param cr A cairo context
 -- @tparam number width The shape width
 -- @tparam number height The shape height
+-- @noreturn
 -- @staticfct gears.shape.isosceles_triangle
 function module.isosceles_triangle(cr, width, height)
     cr:move_to( width/2, 0      )
@@ -472,6 +486,7 @@ end
 -- @tparam number width The shape width
 -- @tparam number height The shape height
 -- @tparam[opt=width/3] number thickness The cross section thickness
+-- @noreturn
 -- @staticfct gears.shape.cross
 function module.cross(cr, width, height, thickness)
     thickness = thickness or width/3
@@ -500,6 +515,7 @@ end
 -- @tparam number width The shape width
 -- @tparam number height The shape height
 -- @tparam number corner_radius
+-- @noreturn
 -- @staticfct gears.shape.octogon
 function module.octogon(cr, width, height, corner_radius)
     corner_radius = corner_radius or math.min(10, math.min(width, height)/4)
@@ -524,6 +540,7 @@ end
 -- @tparam number width The shape width
 -- @tparam number height The shape height
 -- @tparam[opt=math.min(width  height) / 2)] number radius The radius
+-- @noreturn
 -- @staticfct gears.shape.circle
 function module.circle(cr, width, height, radius)
     radius = radius or math.min(width, height) / 2
@@ -539,6 +556,7 @@ end
 -- @param cr A cairo context
 -- @tparam number width The shape width
 -- @tparam number height The shape height
+-- @noreturn
 -- @staticfct gears.shape.rectangle
 function module.rectangle(cr, width, height)
     cr:rectangle(0, 0, width, height)
@@ -553,6 +571,7 @@ end
 -- @tparam number width The shape width
 -- @tparam number height The shape height
 -- @tparam[opt=width/3] number base_width The parallelogram base width
+-- @noreturn
 -- @staticfct gears.shape.parallelogram
 function module.parallelogram(cr, width, height, base_width)
     base_width = base_width or width/3
@@ -570,6 +589,7 @@ end
 -- @param cr A cairo context
 -- @tparam number width The shape width
 -- @tparam number height The shape height
+-- @noreturn
 -- @staticfct gears.shape.losange
 function module.losange(cr, width, height)
     cr:move_to(width/2 , 0        )
@@ -591,6 +611,7 @@ end
 -- @tparam[opt=0] number start_angle The start angle (in radian)
 -- @tparam[opt=math.pi/2] number end_angle The end angle (in radian)
 -- @tparam[opt=math.min(width height)/2] number radius The shape height
+-- @noreturn
 -- @staticfct gears.shape.pie
 function module.pie(cr, width, height, start_angle, end_angle, radius)
     radius = radius or math.floor(math.min(width, height)/2)
@@ -627,8 +648,9 @@ end
 -- @tparam[opt=math.min(width height)/2] number thickness The arc thickness
 -- @tparam[opt=0] number start_angle The start angle (in radian)
 -- @tparam[opt=math.pi/2] number end_angle The end angle (in radian)
--- @tparam[opt=false] boolean start_rounded if the arc start rounded
--- @tparam[opt=false] boolean end_rounded if the arc end rounded
+-- @tparam[opt=false] boolean start_rounded If the arc start rounded
+-- @tparam[opt=false] boolean end_rounded If the arc end rounded
+-- @noreturn
 -- @staticfct gears.shape.arc
 function module.arc(cr, width, height, thickness, start_angle, end_angle, start_rounded, end_rounded)
     start_angle = start_angle or 0
@@ -752,6 +774,7 @@ end
 -- @tparam number h The shape height
 -- @tparam number percent The progressbar percent
 -- @tparam boolean hide_left Do not draw the left side of the shape
+-- @noreturn
 -- @staticfct gears.shape.radial_progress
 function module.radial_progress(cr, w, h, percent, hide_left)
     percent = percent or 1
@@ -820,6 +843,12 @@ end
 -- @param shape A shape function
 -- @return A transformation handle, also act as a shape function
 -- @staticfct gears.shape.transform
+-- @see gears.matrix.translate
+-- @see gears.matrix.scale
+-- @see gears.matrix.rotate
+-- @see gears.matrix.rotate_at
+-- @see gears.matrix.multiply
+-- @see gears.matrix.invert
 function module.transform(shape)
 
     -- Apply the transformation matrix and apply the shape, then restore

lib/gears/sort/init.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- Extra sorting algorithms.
+--- Utilities to sort and arrange data.
 --
 -- @utillib gears.sort
 ---------------------------------------------------------------------------

lib/gears/sort/topological.lua

@@ -18,6 +18,7 @@ end
 --- Ensure that `node` appears after all `dependencies`.
 -- @param node The node that edges are added to.
 -- @tparam table dependencies List of nodes that have to appear before `node`.
+-- @noreturn
 -- @method append
 function tsort:append(node, dependencies)
     add_node(self, node)
@@ -30,6 +31,7 @@ end
 --- Ensure that `node` appears before all `subordinates`.
 -- @param node The node that edges are added to.
 -- @tparam table subordinates List of nodes that have to appear after `node`.
+-- @noreturn
 -- @method prepend
 function tsort:prepend(node, subordinates)
     for _, dep in ipairs(subordinates) do
@@ -65,6 +67,7 @@ end
 --- Create a copy of this topological sort.
 -- This is useful to backup it before adding elements that can potentially
 -- have circular dependencies and thus render the original useless.
+-- @treturn gears.sort.topological The cloned sorter object.
 -- @method clone
 function tsort:clone()
     local new = tsort.topological()
@@ -78,6 +81,7 @@ end
 --- Remove a node from the topological map.
 --
 -- @param node The node
+-- @noreturn
 -- @method remove
 function tsort:remove(node)
     self._edges[node] = nil

lib/gears/string.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- String module for gears.
+--- Various string manipulation and introspection fuctions.
 --
 -- @utillib gears.string
 ---------------------------------------------------------------------------
@@ -10,7 +10,7 @@ local xml_entity_names = { ["'"] = "&apos;", ["\""] = "&quot;", ["<"] = "&lt;",
 
 --- Escape a string from XML char.
 -- Useful to set raw text in textbox.
--- @param text Text to escape.
+-- @tparam string text Text to escape.
 -- @treturn string Escaped text.
 -- @staticfct gears.string.xml_escape
 function gstring.xml_escape(text)
@@ -21,7 +21,7 @@ local xml_entity_chars = { lt = "<", gt = ">", nbsp = " ", quot = "\"", apos = "
                            amp = "&" };
 
 --- Unescape a string from entities.
--- @param text Text to unescape.
+-- @tparam string text Text to unescape.
 -- @treturn string Unescaped text.
 -- @staticfct gears.string.xml_unescape
 function gstring.xml_unescape(text)
@@ -74,6 +74,7 @@ end
 
 --- Generate a pattern matching expression that ignores case.
 -- @tparam string q Original pattern matching expression.
+-- @treturn string The pattern.
 -- @staticfct gears.string.query_to_pattern
 function gstring.query_to_pattern(q)
     local s = gstring.quote_pattern(q)

lib/gears/surface.lua

@@ -1,4 +1,6 @@
 ---------------------------------------------------------------------------
+-- Utilities to integrate and manipulate Cairo drawing surfaces.
+--
 -- @author Uli Schlachter
 -- @copyright 2012 Uli Schlachter
 -- @module gears.surface
@@ -9,7 +11,7 @@ local type = type
 local capi = { awesome = awesome }
 local cairo = require("lgi").cairo
 local GdkPixbuf = require("lgi").GdkPixbuf
-local color = nil
+local color, beautiful = nil, nil
 local gdebug = require("gears.debug")
 local hierarchy = require("wibox.hierarchy")
 
@@ -169,8 +171,8 @@ end
 -- @tparam number width The surface width
 -- @tparam number height The surface height
 -- @param shape A `gears.shape` compatible function
--- @param[opt=white] shape_color The shape color or pattern
--- @param[opt=transparent] bg_color The surface background color
+-- @param[opt="#000000"] shape_color The shape color or pattern
+-- @param[opt="#00000000"] bg_color The surface background color
 -- @treturn cairo.surface the new surface
 -- @staticfct load_from_shape
 function surface.load_from_shape(width, height, shape, shape_color, bg_color, ...)
@@ -195,11 +197,11 @@ end
 --
 --  If the wibox or client size change, this function need to be called
 --   again.
--- @param draw A wibox or a client
--- @param shape or gears.shape function or a custom function with a context,
---   width and height as parameter.
--- @param[opt] Any additional parameters will be passed to the shape function.
+-- @tparam client|wibox draw A wibox or a client.
+-- @tparam gears.shape|function shape The shape.
+-- @param[opt] ... Any additional parameters will be passed to the shape function.
 -- @staticfct apply_shape_bounding
+-- @noreturn
 function surface.apply_shape_bounding(draw, shape, ...)
   local geo = draw:geometry()
 
@@ -232,7 +234,7 @@ end
 --- Create an SVG file with this widget content.
 -- This is dynamic, so the SVG will be updated along with the widget content.
 -- because of this, the painting may happen hover multiple event loop cycles.
--- @deprecated draw_to_svg_file
+-- @deprecated widget_to_svg
 -- @tparam widget widget A widget
 -- @tparam string path The output file path
 -- @tparam number width The surface width
@@ -243,17 +245,22 @@ end
 -- @see wibox.widget.draw_to_image_surface
 function surface.widget_to_svg(widget, path, width, height)
     gdebug.deprecate("Use wibox.widget.draw_to_svg_file instead of "..
-        "gears.surface.render_to_svg", {deprecated_in=5})
+        "gears.surface.widget_to_svg", {deprecated_in=5})
     local img = cairo.SvgSurface.create(path, width, height)
     local cr = cairo.Context(img)
 
+    -- Bad dependecy, but this is deprecated.
+    beautiful = beautiful or require("beautiful")
+    color = color or require("gears.color")
+    cr:set_source(color(beautiful.fg_normal))
+
     return img, run_in_hierarchy(widget, cr, width, height)
 end
 
 --- Create a cairo surface with this widget content.
 -- This is dynamic, so the SVG will be updated along with the widget content.
 -- because of this, the painting may happen hover multiple event loop cycles.
--- @deprecated draw_to_image_surface
+-- @deprecated widget_to_surface
 -- @tparam widget widget A widget
 -- @tparam number width The surface width
 -- @tparam number height The surface height
@@ -268,6 +275,11 @@ function surface.widget_to_surface(widget, width, height, format)
     local img = cairo.ImageSurface(format or cairo.Format.ARGB32, width, height)
     local cr = cairo.Context(img)
 
+    -- Bad dependecy, but this is deprecated.
+    color = color or require("gears.color")
+    beautiful = beautiful or require("beautiful")
+    cr:set_source(color(beautiful.fg_normal))
+
     return img, run_in_hierarchy(widget, cr, width, height)
 end
 

lib/gears/table.lua

@@ -1,8 +1,8 @@
 ---------------------------------------------------------------------------
---- Table module for gears.
+--- Various functions to worj with tables.
 --
 -- Examples
--- =======
+-- ========
 --
 -- Using `cycle_value`, you can cycle through values in a table.
 -- When the end of the table is reached, `cycle_value` loops around to the beginning.

lib/gears/timer.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- Timer objects and functions.
+--- Class to execute code at specific intervals.
 --
 -- @usage
 --    -- Create a widget and update its content using the output of a shell
@@ -91,6 +91,7 @@ local timer = { mt = {} }
 
 --- Start the timer.
 -- @method start
+-- @noreturn
 -- @emits start
 function timer:start()
     if self.data.source_id ~= nil then
@@ -110,6 +111,7 @@ end
 -- Does nothing if the timer isn't running.
 --
 -- @method stop
+-- @noreturn
 -- @emits stop
 function timer:stop()
     if self.data.source_id == nil then
@@ -124,6 +126,7 @@ end
 -- This is equivalent to stopping the timer if it is running and then starting
 -- it.
 -- @method again
+-- @noreturn
 -- @emits start
 -- @emits stop
 function timer:again()
@@ -134,13 +137,20 @@ function timer:again()
 end
 
 --- The timer is started.
+--
+-- For this to be `true` by default, pass `autostart` to the constructor.
+--
 -- @property started
--- @param boolean
+-- @tparam[opt=false] boolean started
+-- @see start
+-- @see stop
 
 --- The timer timeout value.
--- **Signal:** property::timeout
+--
 -- @property timeout
--- @param number
+-- @tparam[opt=0] number timeout
+-- @propertyunit second
+-- @negativeallowed false
 -- @propemits true false
 
 local timer_instance_mt = {
@@ -264,6 +274,7 @@ local delayed_calls = {}
 -- all, because it means that less batching happens and the delayed calls run
 -- prematurely.
 -- @staticfct gears.timer.run_delayed_calls_now
+-- @noreturn
 function timer.run_delayed_calls_now()
     for _, callback in ipairs(delayed_calls) do
         protected_call(unpack(callback))
@@ -274,6 +285,7 @@ end
 --- Call the given function at the end of the current GLib event loop iteration.
 -- @tparam function callback The function that should be called
 -- @param ... Arguments to the callback function
+-- @noreturn
 -- @staticfct gears.timer.delayed_call
 function timer.delayed_call(callback, ...)
     assert(type(callback) == "function", "callback must be a function, got: " .. type(callback))

lib/menubar/icon_theme.lua

@@ -82,6 +82,7 @@ local index_theme_cache = {}
 -- @tparam string icon_theme_name Internal name of icon theme
 -- @tparam table base_directories Paths used for lookup
 -- @treturn table An instance of the class `icon_theme`
+-- @usebeautiful beautiful.icon_theme
 icon_theme.new = function(icon_theme_name, base_directories)
     icon_theme_name = icon_theme_name or beautiful.icon_theme or get_default_icon_theme_name()
     base_directories = base_directories or get_pragmatic_base_directories()

lib/menubar/init.lua

@@ -395,7 +395,8 @@ local function menulist_update(scr)
 end
 
 --- Refresh menubar's cache by reloading .desktop files.
--- @tparam[opt] screen scr Screen.
+-- @tparam[opt=awful.screen.focused()] screen scr Screen.
+-- @noreturn
 -- @staticfct menubar.refresh
 function menubar.refresh(scr)
     scr = get_screen(scr or awful.screen.focused() or 1)
@@ -452,8 +453,16 @@ local function prompt_keypressed_callback(mod, key, comm)
 end
 
 --- Show the menubar on the given screen.
--- @param[opt] scr Screen.
+-- @tparam[opt=awful.screen.focused()] screen scr Screen.
+-- @noreturn
 -- @staticfct menubar.show
+-- @usebeautiful beautiful.menubar_fg_normal
+-- @usebeautiful beautiful.menubar_bg_normal
+-- @usebeautiful beautiful.menubar_border_width
+-- @usebeautiful beautiful.menubar_border_color
+-- @usebeautiful beautiful.menubar_fg_focus
+-- @usebeautiful beautiful.menubar_bg_focus
+-- @usebeautiful beautiful.menubar_font
 function menubar.show(scr)
     scr = get_screen(scr or awful.screen.focused() or 1)
     local fg_color = theme.menubar_fg_normal or theme.menu_fg_normal or theme.fg_normal
@@ -533,6 +542,7 @@ end
 
 --- Hide the menubar.
 -- @staticfct menubar.hide
+-- @noreturn
 function menubar.hide()
     if instance then
         instance.wibox.visible = false

lib/menubar/menu_gen.lua

@@ -57,8 +57,7 @@ menu_gen.all_categories = {
                 icon_name = "applications-accessories", use = true }
 }
 
---- Find icons for category entries.
--- @staticfct menubar.menu_gen.lookup_category_icons
+-- Find icons for category entries.
 function menu_gen.lookup_category_icons()
     for _, v in pairs(menu_gen.all_categories) do
         v.icon = utils.lookup_icon(v.icon_name)
@@ -81,6 +80,7 @@ end
 -- with the resulting list of menu entries as argument.
 -- @tparam table callback.entries All menu entries.
 -- @staticfct menubar.menu_gen.generate
+-- @noreturn
 function menu_gen.generate(callback)
     -- Update icons for category entries
     menu_gen.lookup_category_icons()

lib/menubar/utils.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- Utility module for menubar
+--- Utility functions for the `menubar` module.
 --
 -- @author Antonio Terceiro
 -- @copyright 2009, 2011-2012 Antonio Terceiro, Alexander Yakushev
@@ -199,8 +199,9 @@ local function get_icon_lookup_path()
 end
 
 --- Remove CR newline from the end of the string.
--- @param s string to trim
+-- @tparam string s The string to trim
 -- @staticfct menubar.utils.rtrim
+-- @treturn string The trimmed string.
 function utils.rtrim(s)
     if not s then return end
     if string.byte(s, #s) == 13 then
@@ -357,6 +358,7 @@ end
 -- with the resulting list of menu entries as argument.
 -- @tparam table callback.programs Paths of found .desktop files.
 -- @staticfct menubar.utils.parse_dir
+-- @noreturn
 function utils.parse_dir(dir_path, callback)
 
     local function get_readable_path(file)

lib/naughty/action.lua

@@ -27,6 +27,7 @@ local action = {}
 -- The action name.
 -- @property name
 -- @tparam string name The name.
+-- @propertydefault This is provided by DBus.
 -- @propemits true false
 
 -- If the action is selected.
@@ -35,17 +36,19 @@ local action = {}
 -- implement keyboard navigation.
 --
 -- @property selected
--- @param boolean
+-- @tparam[opt=false] boolean selected
 -- @propemits true false
 
 --- The action position (index).
 -- @property position
--- @param number
+-- @tparam integer position
+-- @propertydefault This is provided by DBus.
 -- @propemits true false
+-- @negativeallowed false
 
 --- The action icon.
 -- @property icon
--- @tparam gears.surface|string icon
+-- @tparam[opt=nil] image|string|nil icon
 -- @propemits true false
 
 --- If the action should hide the label and only display the icon.
@@ -53,7 +56,7 @@ local action = {}
 -- @DOC_wibox_nwidget_actionlist_icon_only_EXAMPLE@
 --
 -- @property icon_only
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean icon_only
 -- @propemits true false
 
 --- When a notification is invoked.
@@ -120,6 +123,7 @@ end
 --  the action was invoked. If a notification is shared by many object (like
 --  a "mute" or "snooze" action added to all notification), calling `:invoke()`
 --  without adding the `notif` context will cause unexpected results.
+-- @noreturn
 function action:invoke(notif)
     self:emit_signal("invoked", notif)
 end

lib/naughty/container/background.lua

@@ -1,5 +1,5 @@
 ----------------------------------------------------------------------------
---- A notification background.
+--- A notification background widget.
 --
 -- This widget holds the boilerplate code associated with the notification
 -- background. This includes the color and potentially some other styling
@@ -16,6 +16,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2019 Emmanuel Lepage Vallee
 -- @containermod naughty.widget.background
+-- @supermodule wibox.container.background
 -- @see wibox.container.background
 ----------------------------------------------------------------------------
 local wbg       = require("wibox.container.background")
@@ -43,6 +44,7 @@ end
 --- The attached notification.
 -- @property notification
 -- @tparam naughty.notification notification
+-- @propertydefault This is usually set in the construtor.
 -- @propemits true false
 
 function background:set_notification(notif)
@@ -100,8 +102,6 @@ local function new(args)
     return bg
 end
 
---@DOC_widget_COMMON@
-
 --@DOC_object_COMMON@
 
 return setmetatable(background, {__call = function(_, ...) return new(...) end})

lib/naughty/core.lua

@@ -24,20 +24,23 @@ local naughty = {}
 
 --- Naughty configuration - a table containing common popup settings.
 --
+-- The callback has the follwing format:
+--
+--     naughty.config.notify_callback = function(args)
+--         args.text = 'prefix: ' .. args.text
+--         return args
+--     end
+--
 -- @table naughty.config
--- @tfield[opt=apply_dpi(4)] int padding Space between popups and edge of the
+-- @tfield[opt=beautiful.xresources.apply_dpi(4)] integer padding Space between popups and edge of the
 --   workarea.
--- @tfield[opt=apply_dpi(1)] int spacing Spacing between popups.
+-- @tfield[opt=beautiful.xresources.apply_dpi(1)] integer spacing Spacing between popups.
 -- @tfield[opt={"/usr/share/pixmaps/"}] table icon_dirs List of directories
 --   that will be checked by `getIcon()`.
 -- @tfield[opt={ "png", "gif" }] table icon_formats List of formats that will be
 --   checked by `getIcon()`.
 -- @tfield[opt] function notify_callback Callback used to modify or reject
 -- notifications, e.g.
---     naughty.config.notify_callback = function(args)
---         args.text = 'prefix: ' .. args.text
---         return args
---     end
 --   To reject a notification return `nil` from the callback.
 --   If the notification is a freedesktop notification received via DBUS, you can
 --   access the freedesktop hints via `args.freedesktop_hints` if any where
@@ -45,7 +48,7 @@ local naughty = {}
 --
 -- @tfield table presets Notification presets.  See `config.presets`.
 --
--- @tfield table defaults Default values for the params to `notify()`.  These can
+-- @tfield table defaults Default values for the params to `naughty.notification{}`.  These can
 --   optionally be overridden by specifying a preset.  See `config.defaults`.
 
 -- It's done that way to preserve compatibility with Awesome 4.0 while allowing
@@ -55,46 +58,61 @@ gtable.crush(naughty, require("naughty.constants"))
 
 --- Notification presets for `naughty.notify`.
 -- This holds presets for different purposes.  A preset is a table of any
--- parameters for `notify()`, overriding the default values
+-- parameters for `naughty.notification{}`, overriding the default values
 -- (`naughty.config.defaults`).
 --
--- You have to pass a reference of a preset in your `notify()` as the `preset`
+-- You have to pass a reference of a preset in your `naughty.notification{}` as the `preset`
 -- argument.
 --
 -- The presets `"low"`, `"normal"` and `"critical"` are used for notifications
 -- over DBUS.
 --
--- @table config.presets
+-- @table naughty.config.presets
 -- @tfield table low The preset for notifications with low urgency level.
--- @tfield[opt=5] int low.timeout
--- @tfield[opt=empty] table normal The default preset for every notification without a
+-- @tfield[opt=5] integer low.timeout
+-- @tfield[opt={}] table normal The default preset for every notification without a
 --   preset that will also be used for normal urgency level.
+-- @tfield table ok
+-- @tfield[opt="#00bb00"] string ok.bg
+-- @tfield[opt="#ffffff"] string ok.fg
+-- @tfield[opt=5] integer ok.timeout
 -- @tfield table critical The preset for notifications with a critical urgency
 --   level.
 -- @tfield[opt="#ff0000"] string critical.bg
 -- @tfield[opt="#ffffff"] string critical.fg
--- @tfield[opt=0] string critical.timeout
+-- @tfield[opt=0] integer critical.timeout
+-- @tfield table info
+-- @tfield[opt="#0000ff"] string info.bg
+-- @tfield[opt="#ffffff"] string info.fg
+-- @tfield[opt=5] integer info.timeout
+-- @tfield table warn
+-- @tfield[opt="#ffaa00"] string warn.bg
+-- @tfield[opt="#00000"] string warn.fg
+-- @tfield[opt=5] integer warn.timeout
 
 --- Defaults for `naughty.notify`.
 --
--- @table config.defaults
--- @tfield[opt=5] int timeout
+-- @table naughty.config.defaults
+-- @tfield[opt=5] integer timeout
 -- @tfield[opt=""] string text
--- @tfield[opt] int screen Defaults to `awful.screen.focused`.
+-- @tfield[opt=awful.screen.focused()] integer screen
 -- @tfield[opt=true] boolean ontop
--- @tfield[opt=apply_dpi(5)] int margin
--- @tfield[opt=apply_dpi(1)] int border_width
+-- @tfield[opt=beautiful.xresources.apply_dpi(5)] integer margin
+-- @tfield[opt=beautiful.xresources.apply_dpi(1)] integer border_width
 -- @tfield[opt="top_right"] string position
 
 --- The reason why a notification is to be closed.
+--
 -- See [the specification](https://developer.gnome.org/notification-spec/#signals)
 -- for more details.
--- @tfield number silent
--- @tfield number expired
--- @tfield number dismissed_by_user
--- @tfield number dismissed_by_command
--- @tfield number undefined
--- @table notification_closed_reason
+--
+-- @table naughty.notification_closed_reason
+-- @tfield[opt=-2] number too_many_on_screen
+-- @tfield[opt=-1] number silent
+-- @tfield[opt=1] number expired
+-- @tfield[opt=2] number dismissed_by_user
+-- @tfield[opt=3] number dismissed_by_command
+-- @tfield[opt=4] number undefined
 
 --- The global suspension state.
 --
@@ -102,7 +120,7 @@ gtable.crush(naughty, require("naughty.constants"))
 -- useful when watching movies or doing presentations.
 --
 -- @property suspended
--- @param boolean
+-- @tparam[opt=false] boolean suspended
 -- @emits added
 -- @propemits true false
 
@@ -113,24 +131,26 @@ gtable.crush(naughty, require("naughty.constants"))
 -- just vanish.
 --
 -- @property expiration_paused
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean expiration_paused
 -- @propemits true false
 
 --- A table with all active notifications.
 --
 -- Please note that this list is kept up-to-date even in suspended mode.
 --
--- **Signal:**
---
--- * property::active
---
 -- @property active
--- @param table
+-- @tparam[opt={}] table active
+-- @tablerowtype A list of `naughty.notification` objects.
 -- @propemits false false
 
 --- True when there is a handler connected to `request::display`.
+--
+-- Note that using the legacy notifications is deprecated.
+--
 -- @property has_display_handler
--- @param boolean
+-- @tparam boolean has_display_handler
+-- @propertydefault If `rc.lua` has a `request::display` section, this will
+--  be `true`. Otherwise it is `false` and the legacy notification will be used.
 
 --- If the timeout needs to be reset when a property changes.
 --
@@ -148,7 +168,7 @@ gtable.crush(naughty, require("naughty.constants"))
 -- support for this and enabling it will cause bugs.
 --
 -- @property image_animations_enabled
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean image_animations_enabled
 -- @propemits true false
 
 --- Enable or disable the persistent notifications.
@@ -164,7 +184,7 @@ gtable.crush(naughty, require("naughty.constants"))
 -- that.
 --
 -- @property persistence_enabled
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean persistence_enabled
 -- @propemits true false
 
 local properties = {
@@ -177,16 +197,6 @@ local properties = {
 
 --TODO v5 Deprecate the public `naughty.notifications` (to make it private)
 
---- Index of notifications per screen and position.
--- See config table for valid 'position' values.
--- Each element is a table consisting of:
---
--- @field box Wibox object containing the popup
--- @field height Popup height
--- @field width Popup width
--- @field die Function to be executed on timeout
--- @field id Unique notification id based on a counter
--- @table notifications
 naughty.notifications = { suspended = { }, _expired = {{}} }
 
 naughty._active = {}
@@ -339,9 +349,9 @@ end
 -- This function is deprecated in favor of
 -- `notification:destroy(reason, keep_visible)`.
 --
--- @param notification Notification object to be destroyed
--- @param reason One of the reasons from `notification_closed_reason`
--- @param[opt=false] keep_visible If true, keep the notification visible
+-- @tparam naughty.notification notification Notification object to be destroyed
+-- @tparam string reason One of the reasons from `notification_closed_reason`
+-- @tparam[opt=false] boolean keep_visible If true, keep the notification visible
 -- @return True if the popup was successfully destroyed, nil otherwise
 -- @deprecated naughty.destroy
 function naughty.destroy(notification, reason, keep_visible)
@@ -385,8 +395,8 @@ end
 
 --- Get notification by ID
 --
--- @param id ID of the notification
--- @return notification object if it was found, nil otherwise
+-- @tparam integer id ID of the notification
+-- @treturn naughty.notification|nil notification object if it was found, nil otherwise
 -- @deprecated naughty.getById
 function naughty.getById(id)
     gdebug.deprecate("Use naughty.get_by_id", {deprecated_in=5})
@@ -395,8 +405,8 @@ end
 
 --- Get notification by ID
 --
--- @param id ID of the notification
--- @return notification object if it was found, nil otherwise
+-- @tparam integer id ID of the notification
+-- @treturn naughty.notification|nil notification object if it was found, nil otherwise
 -- @staticfct naughty.get_by_id
 function naughty.get_by_id(id)
     -- iterate the notifications to get the notfications with the correct ID
@@ -749,7 +759,7 @@ end
 -- @int[opt=5] args.timeout Time in seconds after which popup expires.
 --   Set 0 for no timeout.
 -- @int[opt] args.hover_timeout Delay in seconds after which hovered popup disappears.
--- @tparam[opt=focused] integer|screen args.screen Target screen for the notification.
+-- @tparam[opt=awful.screen.focused()] integer|screen args.screen Target screen for the notification.
 -- @string[opt="top_right"] args.position Corner of the workarea displaying the popups.
 --   Values: `"top_right"`, `"top_left"`, `"bottom_left"`,
 --   `"bottom_right"`, `"top_middle"`, `"bottom_middle"`, `"middle"`.
@@ -766,17 +776,17 @@ end
 -- @tparam[opt=`beautiful.notification_shape`] gears.shape args.shape Widget shape.
 -- @tparam[opt=`beautiful.notification_opacity`] gears.opacity args.opacity Widget opacity.
 -- @tparam[opt=`beautiful.notification_margin`] gears.margin args.margin Widget margin.
--- @tparam[opt] func args.run Function to run on left click.  The notification
+-- @tparam[opt] function args.run Function to run on left click.  The notification
 --   object will be passed to it as an argument.
 --   You need to call e.g.
 --   `notification.die(naughty.notification_closed_reason.dismissedByUser)` from
 --   there to dismiss the notification yourself.
--- @tparam[opt] func args.destroy Function to run when notification is destroyed.
+-- @tparam[opt] function args.destroy Function to run when notification is destroyed.
 -- @tparam[opt] table args.preset Table with any of the above parameters.
 --   Note: Any parameters specified directly in args will override ones defined
 --   in the preset.
--- @tparam[opt] int args.replaces_id Replace the notification with the given ID.
--- @tparam[opt] func args.callback Function that will be called with all arguments.
+-- @tparam[opt] integer args.replaces_id Replace the notification with the given ID.
+-- @tparam[opt] function args.callback 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.
 -- @tparam[opt] table args.actions A list of `naughty.action`s.

lib/naughty/init.lua

@@ -1,4 +1,6 @@
 ---------------------------------------------------------------------------
+-- Desktop notification handling library.
+--
 -- @author Uli Schlachter <psychon@znc.in>
 -- @copyright 2014 Uli Schlachter
 -- @module naughty

lib/naughty/layout/box.lua

@@ -167,6 +167,7 @@ end)
 --
 -- @property notification
 -- @tparam naughty.notification notification
+-- @propertydefault This must be provided by the constructor.
 -- @propemits true false
 
 --- The widget template to construct the box content.
@@ -208,7 +209,7 @@ end)
 --    }
 --
 -- @property widget_template
--- @param widget
+-- @tparam[opt=nil] template|nil widget_template
 -- @usebeautiful beautiful.notification_max_width The maximum width for the
 --  resulting widget.
 
@@ -396,6 +397,4 @@ local function new(args)
     return ret
 end
 
---@DOC_wibox_COMMON@
-
 return setmetatable(box, {__call = function(_, args) return new(args) end})

lib/naughty/layout/legacy.lua

@@ -1,5 +1,5 @@
 ----------------------------------------------------------------------------
---- A notification popup widget.
+--- A notification popup widget (deprecated implementation).
 --
 -- This is the legacy notification widget. It was the default until Awesome
 -- v4.3 but is now being deprecated in favor of a more flexible widget.

lib/naughty/list/actions.lua

@@ -24,6 +24,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2017 Emmanuel Lepage Vallee
 -- @widgetmod naughty.list.actions
+-- @supermodule wibox.widget.base
 -- @see awful.widget.common
 ----------------------------------------------------------------------------
 
@@ -188,7 +189,7 @@ local actionlist = {}
 
 --- The actionlist parent notification.
 -- @property notification
--- @tparam naughty.notification notification
+-- @tparam[opt=nil] naughty.notification|nil notification
 -- @propemits true false
 -- @see naughty.notification
 
@@ -196,18 +197,33 @@ local actionlist = {}
 -- If no layout is specified, a `wibox.layout.fixed.horizontal` will be created
 -- automatically.
 -- @property base_layout
--- @tparam widget base_layout
+-- @tparam[opt=wibox.layout.fixed.horizontal] widget base_layout
 -- @propemits true false
 -- @see wibox.layout.fixed.horizontal
 
 --- The actionlist parent notification.
 -- @property widget_template
--- @tparam table widget_template
+-- @tparam[opt=nil] template|nil widget_template
 -- @propemits true false
 
 --- A table with values to override each `beautiful.notification_action` values.
 -- @property style
--- @tparam table style
+-- @tparam[opt={}] table|nil style
+-- @tparam boolean|nil style.underline_normal
+-- @tparam boolean|nil style.underline_selected
+-- @tparam shape|nil style.shape_normal
+-- @tparam shape|nil style.shape_selected
+-- @tparam gears.color|string|nil style.shape_border_color_normal
+-- @tparam gears.color|string|nil style.shape_border_color_selected
+-- @tparam number|nil style.shape_border_width_normal
+-- @tparam number|nil style.shape_border_width_selected
+-- @tparam number|nil style.icon_size
+-- @tparam color|string|nil style.bg_normal
+-- @tparam color|string|nil style.bg_selected
+-- @tparam color|string|nil style.fg_normal
+-- @tparam color|string|nil style.fg_selected
+-- @tparam surface|string|nil style.bgimage_normal
+-- @tparam surface|string|nil style.bgimage_selected
 -- @propemits true false
 -- @usebeautiful beautiful.font Fallback when the `font` property isn't set.
 -- @usebeautiful beautiful.notification_action_underline_normal Fallback.
@@ -349,8 +365,6 @@ local function new(_, args)
     return wdg
 end
 
---@DOC_widget_COMMON@
-
 --@DOC_object_COMMON@
 
 return setmetatable(module, {__call = new})

lib/naughty/list/notifications.lua

@@ -6,6 +6,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2017 Emmanuel Lepage Vallee
 -- @widgetmod naughty.list.notifications
+-- @supermodule wibox.widget.base
 -- @see awful.widget.common
 ----------------------------------------------------------------------------
 
@@ -160,16 +161,17 @@ local notificationlist = {}
 --- The notificationlist parent notification.
 -- @property notification
 -- @tparam naughty.notification notification
+-- @propertydefault This is usually set in the construtor.
 -- @propemits true false
 -- @see naughty.notification
 
 --- A `wibox.layout` to be used to place the entries.
 --
--- If no layout is specified, a `wibox.layout.fixed.vertical` will be created
+-- If no layout is specified, a `wibox.layout.flex.horizontal` will be created
 -- automatically.
 --
 -- @property base_layout
--- @tparam widget base_layout
+-- @tparam[opt=wibox.layout.flex.horizontal] widget base_layout
 -- @propemits true false
 -- @usebeautiful beautiful.notification_spacing
 -- @see wibox.layout.fixed.horizontal
@@ -180,12 +182,15 @@ local notificationlist = {}
 
 --- The notificationlist parent notification.
 -- @property widget_template
--- @tparam table widget_template
+-- @tparam[opt=nil] template|nil widget_template
+-- @propertydefault The default template displays the icon, title, message and
+--  actions.
 -- @propemits true false
 
 --- A table with values to override each `beautiful.notification_action` values.
 -- @property style
--- @tparam table style
+-- @tparam[opt=nil] table|nil style
+-- @propertytype nil Use the values from `beautiful` rather than hardcoded ones.
 -- @propemits true false
 -- @usebeautiful beautiful.notification_shape_normal Fallback.
 -- @usebeautiful beautiful.notification_shape_selected Fallback.
@@ -242,7 +247,11 @@ end
 
 --- A function to prevent some notifications from being added to the list.
 -- @property filter
--- @tparam function filter
+-- @tparam[opt=nil] function|nil filter
+-- @functionparam naughty.notification n The notification object.
+-- @functionparam number count The number of notifications in the list.
+-- @functionreturn boolean `true` if the notification is allowed and `false` if
+--  it is rejected.
 -- @propemits true false
 
 for _, prop in ipairs { "filter", "base_layout" } do
@@ -367,8 +376,6 @@ function module.filter.most_recent(n, count)
     return false
 end
 
---@DOC_widget_COMMON@
-
 --@DOC_object_COMMON@
 
 return setmetatable(module, {__call = new})

lib/naughty/notification.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- A notification object.
+--- Notification manipulation class.
 --
 -- This class creates individual notification objects that can be manipulated
 -- to extend the default behavior.
@@ -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
--- @param string
+-- @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.
@@ -167,62 +172,68 @@ local notification = {}
 -- be updated with a date further in the future.
 --
 -- @property resident
--- @param[opt=false] boolean
+-- @tparam[opt=false] boolean resident
 -- @propemits true false
 
 --- Delay in seconds after which hovered popup disappears.
 -- @property hover_timeout
--- @param number
+-- @tparam[opt=nil] number|nil hover_timeout
+-- @negativeallowed false
+-- @propertyunit second
 -- @propemits true false
 
 --- Target screen for the notification.
 -- @property screen
--- @param 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
--- @param string
+-- @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
 
 --- Boolean forcing popups to display on top.
 -- @property ontop
--- @param boolean
+-- @tparam[opt=false] boolean ontop
 
 --- Popup height.
 --
 --@DOC_awful_notification_geometry_EXAMPLE@
 --
 -- @property height
--- @param number
+-- @tparam number|nil height
 -- @propemits true false
+-- @propertyunit pixel
+-- @negativeallowed false
+-- @propbeautiful
 -- @see width
 
 --- Popup width.
 -- @property width
--- @param number
+-- @tparam number|nil width
 -- @propemits true false
+-- @propertyunit pixel
+-- @negativeallowed false
+-- @propbeautiful
 -- @see height
 
 --- Notification font.
 --@DOC_naughty_colors_EXAMPLE@
 -- @property font
--- @param string
+-- @tparam[opt=beautiful.notification_font] font|nil font
 -- @propemits true false
+-- @see wibox.widget.textbox.font
 
 --- "All in one" way to access the default image or icon.
 --
@@ -241,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
--- @param number
+-- @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.
@@ -257,7 +270,7 @@ local notification = {}
 -- icon name to be fetched from the theme.
 --
 -- @property app_icon
--- @param string
+-- @tparam[opt=nil] string|nil app_icon
 -- @propemits true false
 
 --- The notification image.
@@ -267,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.
@@ -278,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.
@@ -287,7 +303,8 @@ local notification = {}
 --@DOC_awful_notification_fg_EXAMPLE@
 --
 -- @property fg
--- @tparam string|color|pattern fg
+-- @tparam[beautiful.notification_fg] color|nil fg
+-- @propbeautiful
 -- @propemits true false
 -- @see title
 -- @see gears.color
@@ -297,22 +314,27 @@ local notification = {}
 --@DOC_awful_notification_bg_EXAMPLE@
 --
 -- @property bg
--- @tparam 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
--- @param number
+-- @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
--- @param string
+-- @tparam[opt=beautiful.notification_border_color] string|nil border_color
 -- @propemits true false
 -- @see gears.color
 
@@ -331,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.
@@ -344,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
 
@@ -368,14 +401,24 @@ local notification = {}
 -- args will override ones defined
 --   in the preset.
 -- @property preset
--- @param table
+-- @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
--- @param function
+-- @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.
@@ -383,7 +426,8 @@ local notification = {}
 -- The table key (a number) is used by DBus to set map the action.
 --
 -- @property actions
--- @param table
+-- @tparam[opt={}] table actions
+-- @tablerowtype A list of `naughty.action` objects.
 -- @propemits true false
 
 --- Ignore this notification, do not display.
@@ -392,20 +436,23 @@ local notification = {}
 -- handler.
 --
 -- @property ignore
--- @param boolean
+-- @tparam[opt=false] boolean ignore
 -- @propemits true false
 
 --- Tell if the notification is currently suspended (read only).
 --
 -- This is always equal to `naughty.suspended`
---@property suspended
---@param boolean
+-- @property suspended
+-- @tparam[opt=false] boolean suspended
 -- @propemits true false
+-- @see naughty.suspended
 
 --- If the notification is expired.
 -- @property is_expired
--- @param boolean
+-- @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.
@@ -436,7 +483,8 @@ local notification = {}
 -- client.
 --
 -- @property clients
--- @param table
+-- @tparam[opt={}] table clients
+-- @tablerowtype A list of `client` objects.
 
 --- The maximum popup width.
 --
@@ -444,9 +492,12 @@ local notification = {}
 -- this is ignored by `naughty.list.notifications` because it delegate this
 -- decision to the layout.
 --
--- @property[opt=500] max_width
--- @param number
+-- @property max_width
+-- @tparam[opt=500] number|nil max_width
+-- @propertyunit pixel
+-- @negativeallowed false
 -- @propemits true false
+-- @propbeautiful
 
 --- The application name specified by the notification.
 --
@@ -454,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
--- @param string
+-- @tparam[opt=nil] string|nil app_name
 -- @propemits true false
 
 --- The widget template used to represent the notification.
@@ -463,7 +514,8 @@ local notification = {}
 -- off with a specialized notification widget.
 --
 -- @property widget_template
--- @param table
+-- @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.
@@ -496,6 +548,7 @@ end
 --- Set new notification timeout.
 -- @method reset_timeout
 -- @tparam number new_timeout Time in seconds after which notification disappears.
+-- @noreturn
 function notification:reset_timeout(new_timeout)
     if self.timer then self.timer:stop() end
 
@@ -791,6 +844,7 @@ end
 --- Add more actions to the notification.
 -- @method append_actions
 -- @tparam table new_actions
+-- @noreturn
 
 function notification:append_actions(new_actions)
     self._private.actions = self._private.actions or {}
@@ -901,49 +955,50 @@ end
 
 --- Create a notification.
 --
--- @tparam table args The argument table containing any of the arguments below.
--- @string[opt=""] args.text Text of the notification.
--- @string[opt] args.title Title of the notification.
--- @int[opt=5] args.timeout Time in seconds after which popup expires.
+-- @tparam[opt={}] table args The argument table containing any of the arguments below.
+-- @tparam[opt=""] string args.text Text of the notification.
+-- @tparam[opt] string args.title Title of the notification.
+-- @tparam[opt=5] integer args.timeout Time in seconds after which popup expires.
 --   Set 0 for no timeout.
--- @int[opt] args.hover_timeout Delay in seconds after which hovered popup disappears.
+-- @tparam[opt] number args.hover_timeout Delay in seconds after which hovered popup disappears.
 -- @tparam[opt=focused] integer|screen args.screen Target screen for the notification.
--- @string[opt="top_right"] args.position Corner of the workarea displaying the popups.
+-- @tparam[opt="top_right"] string args.position Corner of the workarea displaying the popups.
 --   Values: `"top_right"`, `"top_left"`, `"bottom_left"`,
 --   `"bottom_right"`, `"top_middle"`, `"bottom_middle"`, `"middle"`.
--- @bool[opt=true] args.ontop Boolean forcing popups to display on top.
--- @int[opt=`beautiful.notification_height` or auto] args.height Popup height.
--- @int[opt=`beautiful.notification_width` or auto] args.width Popup width.
--- @string[opt=`beautiful.notification_font` or `beautiful.font` or `awesome.font`] args.font Notification font.
--- @string[opt] args.icon Path to icon.
--- @int[opt] args.icon_size Desired icon size in px.
--- @string[opt=`beautiful.notification_fg` or `beautiful.fg_focus` or `'#ffffff'`] args.fg Foreground color.
--- @string[opt=`beautiful.notification_fg` or `beautiful.bg_focus` or `'#535d6c'`] args.bg Background color.
--- @int[opt=`beautiful.notification_border_width` or 1] args.border_width Border width.
--- @string[opt=`beautiful.notification_border_color` or
---   `beautiful.border_color_active` or `'#535d6c'`] args.border_color Border color.
--- @tparam[opt=`beautiful.notification_shape`] gears.shape args.shape Widget shape.
--- @tparam[opt=`beautiful.notification_opacity`] gears.opacity args.opacity Widget opacity.
--- @tparam[opt=`beautiful.notification_margin`] gears.margin args.margin Widget margin.
--- @tparam[opt] func args.run Function to run on left click.  The notification
+-- @tparam[opt=true] boolean args.ontop Boolean forcing popups to display on top.
+-- @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] 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.
+-- @tparam[opt=`beautiful.notification_border_width` or 1] integer args.border_width Border width.
+-- @tparam[opt=`beautiful.notification_border_color` or `beautiful.border_color_active` or `'#535d6c'`] gears.color args.border_color Border color.
+-- @tparam[opt=beautiful.notification_shape] gears.shape args.shape Widget shape.
+-- @tparam[opt=beautiful.notification_opacity] gears.opacity args.opacity Widget opacity.
+-- @tparam[opt=beautiful.notification_margin] gears.margin args.margin Widget margin.
+-- @tparam[opt] function args.run Function to run on left click.  The notification
 --   object will be passed to it as an argument.
 --   You need to call e.g.
 --   `notification.die(naughty.notification_closed_reason.dismissedByUser)` from
 --   there to dismiss the notification yourself.
--- @tparam[opt] func args.destroy Function to run when notification is destroyed.
+-- @tparam[opt] function args.destroy Function to run when notification is destroyed.
 -- @tparam[opt] table args.preset Table with any of the above parameters.
 --   Note: Any parameters specified directly in args will override ones defined
 --   in the preset.
--- @tparam[opt] func args.callback Function that will be called with all arguments.
+-- @tparam[opt] function args.callback 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.
 -- @tparam[opt] table args.actions A list of `naughty.action`s.
--- @bool[opt=false] args.ignore_suspend If set to true this notification
+-- @tparam[opt=false] boolean args.ignore_suspend If set to true this notification
 --   will be shown even if notifications are suspended via `naughty.suspend`.
--- @usage naughty.notify({ title = "Achtung!", message = "You're idling", timeout = 0 })
--- @treturn ?table The notification object, or nil in case a notification was
---   not displayed.
+-- @treturn naughty.notification A new notification object.
 -- @constructorfct naughty.notification
+-- @usage naughty.notification {
+--     title   = "Achtung!",
+--     message = "You're idling", timeout = 0
+-- }
 local function create(args)
     if cst.config.notify_callback then
         args = cst.config.notify_callback(args)
@@ -1059,6 +1114,7 @@ end
 -- @method grant
 -- @tparam string permission The permission name (just the name, no `request::`).
 -- @tparam string context The reason why this permission is requested.
+-- @noreturn
 -- @see awful.permissions
 
 --- Deny a permission for a notification
@@ -1066,6 +1122,7 @@ end
 -- @method deny
 -- @tparam string permission The permission name (just the name, no `request::`).
 -- @tparam string context The reason why this permission is requested.
+-- @noreturn
 -- @see awful.permissions
 
 pcommon.setup_grant(notification, "notification")

lib/naughty/widget/icon.lua

@@ -1,5 +1,5 @@
 ----------------------------------------------------------------------------
---- A notification square icon.
+--- A notification square icon widget.
 --
 -- This widget is a specialized `wibox.widget.imagebox` with the following extra
 -- features:
@@ -14,6 +14,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2017 Emmanuel Lepage Vallee
 -- @widgetmod naughty.widget.icon
+-- @supermodule wibox.widget.imagebox
 -- @see wibox.widget.imagebox
 ----------------------------------------------------------------------------
 local imagebox = require("wibox.widget.imagebox")
@@ -24,7 +25,7 @@ local dpi = require("beautiful.xresources").apply_dpi
 
 local icon = {}
 
--- The default way to resize the icon.
+--- The default way to resize the icon.
 -- @beautiful beautiful.notification_icon_resize_strategy
 -- @param number
 
@@ -80,6 +81,7 @@ end
 --- The attached notification.
 -- @property notification
 -- @tparam naughty.notification notification
+-- @propertydefault This is usually set in the construtor.
 -- @propemits true false
 
 function icon:set_notification(notif)
@@ -112,12 +114,6 @@ local valid_strategies = {
 
 --- How small icons are handled.
 --
--- Valid values are:
---
--- * **scale**: Scale the icon up to the optimal size.
--- * **center**: Keep the icon size and draw it in the center
--- * **resize**: Change the size of the widget itself (*default*).
---
 -- Note that the size upper bound is defined by
 -- `beautiful.notification_icon_size`.
 --
@@ -126,10 +122,18 @@ local valid_strategies = {
 -- @property resize_strategy
 -- @tparam string resize_strategy
 -- @propemits true false
+-- @propertyvalue "scale" Scale the icon up to the optimal size.
+-- @propertyvalue "center" Keep the icon size and draw it in the center
+-- @propertyvalue "resize" Change the size of the widget itself (*default*).
 -- @usebeautiful beautiful.notification_icon_resize_strategy The fallback when
 --  there is no specified strategy.
 -- @usebeautiful beautiful.notification_icon_size  The size upper bound.
 
+
+--- The default notification icon size.
+-- @beautiful beautiful.notification_icon_size
+-- @tparam number notification_icon_size The size (in pixels).
+
 function icon:set_resize_strategy(strategy)
     assert(valid_strategies[strategy], "Invalid strategy")
 
@@ -177,8 +181,6 @@ local function new(args)
     return tb
 end
 
---@DOC_widget_COMMON@
-
 --@DOC_object_COMMON@
 
 return setmetatable(icon, {__call = function(_, ...) return new(...) end})

lib/naughty/widget/message.lua

@@ -1,5 +1,5 @@
 ----------------------------------------------------------------------------
---- A notification content message.
+--- A notification content message widget.
 --
 -- This widget is a specialized `wibox.widget.textbox` with the following extra
 -- features:
@@ -12,6 +12,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2017 Emmanuel Lepage Vallee
 -- @widgetmod naughty.widget.message
+-- @supermodule wibox.widget.textbox
 -- @see wibox.widget.textbox
 ----------------------------------------------------------------------------
 local textbox = require("wibox.widget.textbox")
@@ -24,6 +25,7 @@ local message = {}
 --- The attached notification.
 -- @property notification
 -- @tparam naughty.notification notification
+-- @propertydefault This is usually set in the construtor.
 -- @propemits true false
 
 function message:set_notification(notif)
@@ -85,8 +87,6 @@ local function new(args)
     return tb
 end
 
---@DOC_widget_COMMON@
-
 --@DOC_object_COMMON@
 
 return setmetatable(message, {__call = function(_, ...) return new(...) end})

lib/naughty/widget/title.lua

@@ -1,5 +1,5 @@
 ----------------------------------------------------------------------------
---- A notification title.
+--- A notification title widget.
 --
 -- This widget is a specialized `wibox.widget.textbox` with the following extra
 -- features:
@@ -12,6 +12,7 @@
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2017 Emmanuel Lepage Vallee
 -- @widgetmod naughty.widget.title
+-- @supermodule wibox.widget.textbox
 -- @see wibox.widget.textbox
 ----------------------------------------------------------------------------
 local textbox = require("wibox.widget.textbox")
@@ -24,6 +25,7 @@ local title = {}
 --- The attached notification.
 -- @property notification
 -- @tparam naughty.notification notification
+-- @propertydefault This is usually set in the construtor.
 -- @propemits true false
 
 function title:set_notification(notif)
@@ -86,8 +88,6 @@ local function new(args)
     return tb
 end
 
---@DOC_widget_COMMON@
-
 --@DOC_object_COMMON@
 
 return setmetatable(title, {__call = function(_, ...) return new(...) end})

lib/ruled/client.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- Rules for clients.
+--- Apply properties to a new client based on pre-determined rules.
 --
 -- This module applies @{rules} to clients during startup (via @{client.manage},
 -- but its functions can be used for client matching in general.
@@ -180,9 +180,10 @@ end
 
 --- Apply ruled.client.rules to a client.
 -- @tparam client c The client.
+-- @noreturn
 -- @staticfct ruled.client.apply
 function module.apply(c)
-    return crules:apply(c)
+    crules:apply(c)
 end
 
 --- Add a new rule to the default set.
@@ -527,7 +528,8 @@ end
 --- Apply properties and callbacks to a client.
 -- @tparam client c The client.
 -- @tparam table props Properties to apply.
--- @tparam[opt] table callbacks Callbacks to apply.
+-- @tparam[opt={}] table callbacks Callbacks to apply.
+-- @noreturn
 -- @staticfct ruled.client.execute
 -- @request client titlebars rules granted The `titlebars_enabled` is set in the
 --  rules.

lib/ruled/notification.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- Rules for notifications.
+--- Apply properties to a new `naughty.notification` based on pre-determined rules.
 --
 --@DOC_wibox_nwidget_rules_urgency_EXAMPLE@
 --
@@ -158,6 +158,7 @@ end
 --
 -- @tparam naughty.notification n The notification.
 -- @staticfct ruled.notification.apply
+-- @noreturn
 function module.apply(n)
     local callbacks, props = {}, {}
 
@@ -179,6 +180,7 @@ end
 --- Add a new rule to the default set.
 -- @tparam table rule A valid rule.
 -- @staticfct ruled.notification.append_rule
+-- @noreturn
 function module.append_rule(rule)
     nrules:append_rule("ruled.notifications", rule)
 end
@@ -186,16 +188,20 @@ end
 --- Add a new rules to the default set.
 -- @tparam table rule A table with rules.
 -- @staticfct ruled.notification.append_rules
+-- @noreturn
 function module.append_rules(rules)
     nrules:append_rules("ruled.notifications", rules)
 end
 
 --- Remove a new rule to the default set.
 -- @tparam table rule A valid rule.
+-- @treturn boolean `true` if the rule was removed.
 -- @staticfct ruled.notification.remove_rule
 function module.remove_rule(rule)
-    nrules:remove_rule("ruled.notifications", rule)
+    local ret = nrules:remove_rule("ruled.notifications", rule)
     module.emit_signal("rule::removed", rule)
+
+    return ret
 end
 
 --- Add a new rule source.