From a87387d9f3c8a58f4a6280acf2fab668f76f1508 Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Mon, 10 Apr 2017 21:57:12 +0200 Subject: [PATCH] doc fixes for awful.mouse.resize, awful.rules, awful.util (#1717) --- lib/awful/mouse/resize.lua | 16 ++++++++-------- lib/awful/rules.lua | 23 +++++++++-------------- lib/awful/util.lua | 3 ++- 3 files changed, 19 insertions(+), 23 deletions(-) diff --git a/lib/awful/mouse/resize.lua b/lib/awful/mouse/resize.lua index 24b4fa2c..15bfe8dd 100644 --- a/lib/awful/mouse/resize.lua +++ b/lib/awful/mouse/resize.lua @@ -89,7 +89,7 @@ function module.add_leave_callback(cb, context) table.insert(callbacks.leave[context], cb) end --- Resize, the drawable. +--- Resize the drawable. -- -- Valid `args` are: -- @@ -99,9 +99,9 @@ end -- * *mode*: The resize mode. -- -- @function awful.mouse.resize --- @tparam client client A client --- @tparam[default=mouse.resize] string context The resizing context --- @tparam[opt={}] table args A set of `awful.placement` arguments +-- @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 {} @@ -156,10 +156,10 @@ local function handler(_, client, context, args) --luacheck: no unused_args capi.mousegrabber.run(function (_mouse) if not client.valid then return end - -- Resize everytime the mouse move (default behavior) + -- Resize everytime the mouse moves (default behavior). if args.mode == "live" then -- Get the new geometry - geo = setmetatable(args.placement(client, args),{__index=args}) + geo = setmetatable(args.placement(client, args), {__index=args}) end -- Execute the move callbacks. This can be used to add features such as @@ -194,8 +194,8 @@ local function handler(_, client, context, args) --luacheck: no unused_args if v then return true end end - -- Only resize after the mouse is released, this avoid losing content - -- in resize sensitive apps such as XTerm or allow external modules + -- Only resize after the mouse is released, this avoids losing content + -- in resize sensitive apps such as XTerm or allows external modules -- to implement custom resizing. if args.mode == "after" then -- Get the new geometry diff --git a/lib/awful/rules.lua b/lib/awful/rules.lua index a78af053..c0337c0d 100644 --- a/lib/awful/rules.lua +++ b/lib/awful/rules.lua @@ -457,28 +457,26 @@ function rules.execute(c, props, callbacks) end -- Some properties need to be handled first. For example, many properties - -- depend that the client is tagged, this isn't yet the case. + -- require that the client is tagged, this isn't yet the case. for prop, handler in pairs(rules.high_priority_properties) do local value = props[prop] - if value ~= nil then if type(value) == "function" then value = value(c, props) end - handler(c, value, props) end - end -- Make sure the tag is selected before the main rules are called. - -- Otherwise properties like "urgent" or "focus" may fail because they - -- will be overiden by various callbacks. - -- Previously, this was done in a second client.manage callback, but caused - -- a race condition where the order the require() would change the output. + -- Otherwise properties like "urgent" or "focus" may fail (if they were + -- overridden by other callbacks). + -- Previously this was done in a second client.manage callback, but caused + -- a race condition where the order of modules being loaded would change + -- the outcome. c:emit_signal("request::tag", nil, {reason="rules"}) - -- By default, rc.lua use no_overlap+no_offscreen placement. This has to + -- By default, rc.lua uses no_overlap+no_offscreen placement. This has to -- be executed before x/y/width/height/geometry as it would otherwise -- always override the user specified position with the default rule. if props.placement then @@ -486,13 +484,12 @@ function rules.execute(c, props, callbacks) rules.extra_properties.placement(c, props.placement, props) end - -- Now that the tags and screen are set, handle the geometry + -- Handle the geometry (since tags and screen are set). if props.height or props.width or props.x or props.y or props.geometry then rules.extra_properties.geometry(c, nil, props) end - -- As most race conditions should now have been avoided, apply the remaining - -- properties. + -- Apply the remaining properties (after known race conditions are handled). for property, value in pairs(props) do if property ~= "focus" and type(value) == "function" then value = value(c, props) @@ -523,12 +520,10 @@ function rules.execute(c, props, callbacks) for prop, handler in pairs(rules.delayed_properties) do if not force_ignore[prop] then local value = props[prop] - if value ~= nil then if type(value) == "function" then value = value(c, props) end - handler(c, value, props) end end diff --git a/lib/awful/util.lua b/lib/awful/util.lua index 11323f7c..4c9eb44f 100644 --- a/lib/awful/util.lua +++ b/lib/awful/util.lua @@ -37,7 +37,8 @@ util.shell = os.getenv("SHELL") or "/bin/sh" -- @deprecated deprecate -- @param[opt] see The message to a new method / function to use. -- @tparam table args Extra arguments --- @tparam boolean args.raw Print the message as-is without the automatic context +-- @tparam boolean args.raw Print the message as-is without the automatic +-- context (but only append a leading dot). -- @tparam integer args.deprecated_in Print the message only when Awesome's -- version is equal to or greater than deprecated_in. -- @see gears.debug