doc: Add documentation in each objects which emit request:: signals.

lib/awful/client.lua

@@ -171,6 +171,8 @@ end
 --   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.
+-- @request client activate client.jumpto granted When a client is activated
+--  because `c:jump_to()` is called.
 function client.object.jump_to(self, merge)
     local s = get_screen(screen.focused())
     -- focus the screen
@@ -302,6 +304,8 @@ end
 -- @staticfct awful.client.swap.global_bydirection
 -- @param dir The direction, can be either "up", "down", "left" or "right".
 -- @client[opt] sel The client.
+-- @request client activate client.swap.global_bydirection granted When a client
+--  could be activated because `awful.client.swap.global_bydirection` was called.
 function client.swap.global_bydirection(dir, sel)
     sel = sel or capi.client.focus
     local scr = get_screen(sel and sel.screen or screen.focused())
@@ -463,6 +467,8 @@ end
 --- Move a client to a tag.
 -- @method move_to_tag
 -- @tparam tag target The tag to move the client to.
+-- @request client activate client.movetotag granted When a client could be
+--  activated because `c:move_to_tag()` was called.
 function client.object.move_to_tag(self, target)
     local s = target.screen
     if self and s then
@@ -526,6 +532,8 @@ end
 -- @tparam[opt=c.screen.index+1] screen s The screen, default to current + 1.
 -- @see screen
 -- @see request::activate
+-- @request client activate client.movetoscreen granted When a client could be
+--  activated because `c:move_to_screen()` was called.
 function client.object.move_to_screen(self, s)
     if self then
         local sc = capi.screen.count()
@@ -798,6 +806,7 @@ function client.floating.get(c)
 end
 
 --- The client floating state.
+--
 -- If the client is part of the tiled layout or free floating.
 --
 -- Note that some windows might be floating even if you
@@ -809,7 +818,13 @@ end
 --  * *property::floating*
 --
 -- @property floating
--- @param boolean The floating state
+-- @tparam boolean floating The floating state.
+-- @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
+--  floating.
+-- @request client border inactive granted When a client stop being active and
+--  is not floating.
 
 function client.object.get_floating(c)
     c = c or capi.client.focus
@@ -1554,6 +1569,8 @@ pcommon.setup_grant(client.object, "client")
 --
 -- @property active
 -- @tparam boolean active
+-- @request client border active granted When a client becomes active.
+-- @request client border inactive granted When a client stop being active.
 -- @see activate
 -- @see request::activate
 -- @see awful.permissions.add_activate_filter

lib/awful/client/focus.lua

@@ -60,6 +60,8 @@ end
 -- @function awful.client.focus.byidx
 -- @param i The index.
 -- @client[opt] c The client.
+-- @request client activate client.focus.byidx granted When `awful.focus.byidx`
+--  is called.
 function focus.byidx(i, c)
     local target = client.next(i, c)
     if target then
@@ -141,6 +143,8 @@ end
 
 --- Focus the previous client in history.
 -- @function awful.client.focus.history.previous
+-- @request client activate client.focus.history.previous granted When
+--  `awful.focus.history.previous` is called.
 function focus.history.previous()
     local sel = capi.client.focus
     local s = sel and sel.screen or screen.focused()
@@ -158,6 +162,8 @@ end
 -- @client[opt] c The client.
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
 -- @function awful.client.focus.bydirection
+-- @request client activate client.focus.bydirection granted When
+--  `awful.focus.bydirection` is called.
 function focus.bydirection(dir, c, stacked)
     local sel = c or capi.client.focus
     if sel then
@@ -183,6 +189,8 @@ end
 -- @client[opt] c The client.
 -- @tparam[opt=false] boolean stacked Use stacking order? (top to bottom)
 -- @function awful.client.focus.global_bydirection
+-- @request client activate client.focus.global_bydirection granted When
+--  `awful.client.focus.global_bydirection` is called.
 function focus.global_bydirection(dir, c, stacked)
     local sel = c or capi.client.focus
     local scr = get_screen(sel and sel.screen or screen.focused())

lib/awful/client/urgent.lua

@@ -62,6 +62,11 @@ end
 -- @function awful.urgent.add
 -- @client c The client object.
 -- @param prop The property which is updated.
+-- @request client border active granted When a client becomes active and is no
+--  longer urgent.
+-- @request client border inactive granted When a client stop being active and
+--  is no longer urgent.
+-- @request client border urgent granted When a client stop becomes urgent.
 function urgent.add(c, prop)
     assert(
         c.urgent ~= nil,

lib/awful/layout/init.lua

@@ -405,7 +405,7 @@ end)
 
 local init_layouts
 init_layouts = function()
-    capi.tag.emit_signal("request::default_layouts")
+    capi.tag.emit_signal("request::default_layouts", "startup")
     capi.tag.disconnect_signal("new", init_layouts)
 
     -- Fallback.

lib/awful/menu.lua

@@ -521,6 +521,8 @@ end
 --   included in the menu.
 -- @return The menu.
 -- @constructorfct awful.menu.clients
+-- @request client activate menu.clients granted When clicking on a clients menu
+--  element.
 function menu.clients(args, item_args, filter)
     local cls_t = {}
     for c in client_iterate(filter or function() return true end) do

lib/awful/mouse/client.lua

@@ -15,7 +15,9 @@ local module = {}
 -- @staticfct awful.mouse.client.move
 -- @param 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
+-- @param finished_cb Deprecated, do not use.
+-- @request client geometry mouse.move granted When `awful.mouse.client.move` is
+--  called.
 function module.move(c, snap, finished_cb) --luacheck: no unused args
     if finished_cb then
         gdebug.deprecate("The mouse.client.move `finished_cb` argument is no longer"..
@@ -99,6 +101,8 @@ end
 -- @tparam string corner The corner to grab on resize. Auto detected by default.
 -- @tparam[opt={}] table args A set of `awful.placement` arguments
 -- @treturn string The corner (or side) name
+-- @request client geometry mouse.resize granted When `awful.mouse.client.resize`
+--  is called.
 function module.resize(c, corner, args)
     c = c or capi.client.focus
 

lib/awful/mouse/resize.lua

@@ -103,7 +103,6 @@ end
 -- @tparam client client A client.
 -- @tparam[default=mouse.resize] string context The resizing context.
 -- @tparam[opt={}] table args A set of `awful.placement` arguments.
-
 local function handler(_, client, context, args) --luacheck: no unused_args
     args = args or {}
     context = context or "mouse.resize"

lib/awful/rules.lua

@@ -529,6 +529,8 @@ end
 -- @tab props Properties to apply.
 -- @tab[opt] callbacks Callbacks to apply.
 -- @staticfct awful.rules.execute
+-- @request client titlebars rules granted The `titlebars_enabled` is set in the
+--  rules.
 
 crules._execute = function(_, c, props, callbacks)
 

lib/awful/screen.lua

@@ -89,6 +89,8 @@ end
 -- or keeps its position relative to the current focused screen.
 -- @staticfct awful.screen.focus
 -- @screen _screen Screen number (defaults / falls back to mouse.screen).
+-- @request client activate screen.focus granted The most recent focused client
+--  for this screen should be re-activated.
 function screen.focus(_screen)
     client = client or require("awful.client")
     if type(_screen) == "number" and _screen > capi.screen.count() then _screen = screen.focused() end
@@ -771,7 +773,9 @@ end
 -- The only default implementation is the one provided by `rc.lua`.
 --
 -- @signal request::desktop_decoration
--- @tparam screen s The screen object.
+-- @tparam string context The context.
+-- @request screen wallpaper added granted When the decorations needs to be
+--  added to a new screen.
 
 --- Emitted when a new screen needs a wallpaper.
 --
@@ -782,7 +786,13 @@ end
 -- The only default implementation is the one provided by `rc.lua`.
 --
 -- @signal request::wallpaper
--- @tparam screen s The screen object.
+-- @tparam string context The context.
+-- @request screen wallpaper added granted When the wallpaper needs to be
+--  added to a new screen.
+-- @request screen wallpaper geometry granted When the wallpaper needs to be
+--  updated because the resolution changed.
+-- @request screen wallpaper dpi granted When the wallpaper needs to be
+--  updated because the DPI changed.
 
 --- When a new (physical) screen area has been added.
 --
@@ -965,15 +975,15 @@ capi.screen.connect_signal("_added", function(s)
     -- metadata. Thus, the DPI may be wrong when setting the wallpaper.
     if s._managed ~= "Lua" then
         s:emit_signal("added")
-        s:emit_signal("request::desktop_decoration")
+        s:emit_signal("request::desktop_decoration", "added")
-        s:emit_signal("request::wallpaper")
+        s:emit_signal("request::wallpaper", "added")
     end
 end)
 
 -- Resize the wallpaper(s)
 for _, prop in ipairs {"geometry", "dpi" } do
     capi.screen.connect_signal("property::"..prop, function(s)
-        s:emit_signal("request::wallpaper")
+        s:emit_signal("request::wallpaper", prop)
     end)
 end
 

lib/awful/spawn.lua

@@ -712,6 +712,8 @@ local raise_rules = {focus = true, switch_to_tags = true, raise = true}
 -- @see awful.rules
 -- @treturn client The client if it already exists.
 -- @staticfct awful.spawn.raise_or_spawn
+-- @request client activate spawn.raise_or_spawn granted Activate a client when
+--  `awful.spawn.raise_or_spawn` is called and the client exists.
 function spawn.raise_or_spawn(cmd, rules, matcher, unique_id, callback)
     local hash = unique_id or hash_command(cmd, rules)
 

lib/awful/tag.lua

@@ -815,6 +815,8 @@ end
 --
 -- @property layouts
 -- @param table
+-- @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 layout
 
@@ -1758,6 +1760,7 @@ capi.tag.connect_signal("request::select", tag.object.view_only)
 -- this, an handler for this request must simply set a new screen
 -- for the tag.
 -- @signal request::screen
+-- @tparam string context Why it was called.
 
 --- Emitted after `request::screen` if no new screen has been set.
 -- The tag will be deleted, this is a last chance to move its clients
@@ -1777,7 +1780,7 @@ end)
 capi.screen.connect_signal("removed", function(s)
     -- First give other code a chance to move the tag to another screen
     for _, t in pairs(s.tags) do
-        t:emit_signal("request::screen")
+        t:emit_signal("request::screen", "removed")
     end
     -- Everything that's left: Tell everyone that these tags go away (other code
     -- could e.g. save clients)

lib/awful/titlebar.lua

@@ -470,12 +470,13 @@ end
 -- when `titlebars_enabled` is not set in the rules.
 -- @tparam client c The client.
 -- @tparam[opt=false] boolean hide_all Hide all titlebars except `keep`
--- @tparam string keep Keep the titlebar at this position
+-- @tparam string keep Keep the titlebar at this position.
+-- @tparam string context The reason why this was called.
 -- @treturn boolean If the titlebars were loaded
-local function load_titlebars(c, hide_all, keep)
+local function load_titlebars(c, hide_all, keep, context)
     if c._request_titlebars_called then return false end
 
-    c:emit_signal("request::titlebars", "awful.titlebar", {})
+    c:emit_signal("request::titlebars", context, {})
 
     if hide_all then
         -- Don't bother checking if it has been created, `.hide` don't works
@@ -582,9 +583,11 @@ end
 -- @param[opt] position The position of the titlebar. Must be one of "left",
 --   "right", "top", "bottom". Default is "top".
 -- @staticfct awful.titlebar.show
+-- @request client titlebars show granted Called when `awful.titlebar.show` is
+--  called.
 function titlebar.show(c, position)
     position = position or "top"
-    if load_titlebars(c, true, position) then return end
+    if load_titlebars(c, true, position, "show") then return end
     local bars = all_titlebars[c]
     local data = bars and bars[position]
     local args = data and data.args
@@ -606,9 +609,11 @@ end
 -- @param[opt] position The position of the titlebar. Must be one of "left",
 --   "right", "top", "bottom". Default is "top".
 -- @staticfct awful.titlebar.toggle
+-- @request client titlebars toggle granted Called when `awful.titlebar.toggle` is
+--  called.
 function titlebar.toggle(c, position)
     position = position or "top"
-    if load_titlebars(c, true, position) then return end
+    if load_titlebars(c, true, position, "toggle") then return end
     local _, size = get_titlebar_function(c, position)(c)
     if size == 0 then
         titlebar.show(c, position)

objects/client.c

@@ -177,6 +177,8 @@
  *  or "startup".
  * @tparam table hints More metadata (currently empty, it exists for compliance
  *  with the other `request::` signals).
+ * @request client border added granted When a new client needs a its initial
+ *  border settings.
  */
 
 /** When a client is going away.
@@ -264,6 +266,7 @@
  * @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 raised?
+ * @request client activate ewmh granted When the client asks to be activated.
  */
 
 /** When an event could lead to the client being activated.
@@ -286,13 +289,18 @@
  *
  */
 
-/**
+/** When something request a client geometry to be modified.
+ *
  * @signal request::geometry
  * @tparam client c The client
  * @tparam string context Why and what to resize. This is used for the
  *   handlers to know if they are capable of applying the new geometry.
  * @tparam[opt={}] table Additional arguments. Each context handler may
  *   interpret this differently.
+ * @request client geometry client_maximize_horizontal granted When a client
+ *  (programmatically) asks for the maximization to be changed.
+ * @request client geometry client_maximize_vertical granted When a client
+ *  (programmatically) asks for the maximization to be changed.
  */
 
 /**
@@ -337,6 +345,7 @@
  * @signal request::default_keybindings
  * @tparam string context The context (currently always "startup").
  * @classsignal
+ * @request client default_keybindings startup granted Sent when AwesomeWM starts.
  */
 
 /** When a client gets tagged.
@@ -691,12 +700,11 @@
  *
  * @DOC_sequences_client_fullscreen_EXAMPLE@
  *
- * **Signal:**
- *
- *  * *property::fullscreen*
- *
  * @property fullscreen
- * @param boolean
+ * @tparam boolean fullscreen
+ * @propemits false false
+ * @request client geometry fullscreen granted When the client must be resized
+ *  because it became (or stop being) fullscreen.
  */
 
 /**
@@ -704,13 +712,11 @@
  *
  * @DOC_sequences_client_maximized_EXAMPLE@
  *
- * **Signal:**
- *
- *  * *property::maximized*
- *
  * @property maximized
- * @param boolean
+ * @tparam boolean maximized
  * @propemits false false
+ * @request client geometry maximized granted When the client must be resized
+ *  because it became (or stop being) maximized.
  * @see request::border
  */
 
@@ -719,12 +725,11 @@
  *
  * @DOC_sequences_client_maximized_horizontal_EXAMPLE@
  *
- * **Signal:**
- *
- *  * *property::maximized\_horizontal*
- *
  * @property maximized_horizontal
- * @param boolean
+ * @tparam boolean maximized_horizontal
+ * @propemits false false
+ * @request client geometry maximized_horizontal granted When the client must be resized
+ *  because it became (or stop being) maximized horizontally.
  */
 
 /**
@@ -732,34 +737,27 @@
  *
  * @DOC_sequences_client_maximized_vertical_EXAMPLE@
  *
- * **Signal:**
- *
- *  * *property::maximized\_vertical*
- *
  * @property maximized_vertical
- * @param boolean
+ * @tparam boolean maximized_vertical
+ * @propemits false false
+ * @request client geometry maximized_vertical granted When the client must be resized
+ *  because it became (or stop being) maximized vertically.
  */
 
 /**
  * The client the window is transient for.
  *
- * **Signal:**
- *
- *  * *property::transient\_for*
- *
  * @property transient_for
  * @param client
+ * @propemits false false
  */
 
 /**
  * Window identification unique to a group of windows.
  *
- * **Signal:**
- *
- *  * *property::group\_window*
- *
  * @property group_window
  * @param client
+ * @propemits false false
  */
 
 /**
@@ -771,10 +769,6 @@
 /**
  * A table with size hints of the client.
  *
- * **Signal:**
- *
- *  * *property::size\_hints*
- *
  * @property size_hints
  * @param table
  * @tfield integer table.user_position
@@ -787,6 +781,7 @@
  * @tfield integer table.min_height
  * @tfield integer table.width_inc
  * @tfield integer table.height_inc
+ * @propemits false false
  * @see size_hints_honor
  */
 
@@ -801,10 +796,6 @@
  * "resize" and "all" are set, this means that all but the resize function
  * should be enabled.
  *
- * **Signal:**
- *
- *  * *property::motif\_wm\_hints*
- *
  * @property motif_wm_hints
  * @param table
  * @tfield[opt] table table.functions
@@ -825,51 +816,40 @@
  * @tfield[opt] string table.input_mode
  * @tfield[opt] table table.status
  * @tfield[opt] boolean table.status.tearoff_window
+ * @propemits false false
  */
 
 /**
  * Set the client sticky, i.e. available on all tags.
  *
- * **Signal:**
- *
- *  * *property::sticky*
- *
  * @property sticky
  * @param boolean
+ * @propemits false false
  */
 
 /**
  * Indicate if the client is modal.
  *
- * **Signal:**
- *
- *  * *property::modal*
- *
  * @property modal
  * @param boolean
+ * @propemits false false
  */
 
 /**
  * True if the client can receive the input focus.
  *
- * **Signal:**
- *
- *  * *property::focusable*
- *
  * @property focusable
  * @param boolean
+ * @propemits false false
  */
 
 /**
  * The client's bounding shape as set by awesome as a (native) cairo surface.
  *
- * **Signal:**
- *
- *  * *property::shape\_bounding*
- *
  * @see gears.surface.apply_shape_bounding
  * @property shape_bounding
  * @param surface
+ * @propemits false false
  */
 
 /**

objects/screen.c

@@ -115,6 +115,8 @@
 /**
  * This signal is emitted when a screen is removed from the setup.
  * @signal removed
+ * @request tag screen removed granted When a screen is removed, `request::screen`
+ *  is called on all screen tags to try to relocate them.
  */
 
 /** This signal is emitted when the list of available screens changes.

objects/tag.c

@@ -206,6 +206,9 @@
 /** When a tag requests to be selected.
  * @signal request::select
  * @tparam string context The reason why it was called.
+ * @request tag select ewmh granted When the client request to be moved to a
+ *  specific virtual desktop. AwesomeWM interprets virtual desktop as indexed
+ *  tags.
  */
 
 /**
@@ -216,6 +219,10 @@
  * to dynamically add new layouts to the list of default layouts.
  *
  * @signal request::default_layouts
+ * @tparam string context The context (currently always "startup").
+ * @classsignal
+ * @request tag default_layouts startup granted When AwesomeWM starts, it queries
+ *  for default layout using this request.
  * @see awful.layout.layouts
  * @see awful.layout.append_default_layout
  * @see awful.layout.remove_default_layout