From dc0d5df4da81207ae05f998843ceff41e94a9bcb Mon Sep 17 00:00:00 2001 From: Lucas Schwiderski <4508454+sclu1034@users.noreply.github.com> Date: Sun, 20 Jun 2021 11:39:15 +0200 Subject: [PATCH] doc: Implement review suggetions Co-authored-by: Aire-One --- lib/awful/titlebar.lua | 38 +++++++++++++++++++------------------- lib/gears/table.lua | 2 +- lib/gears/timer.lua | 4 ++-- objects/client.c | 7 ++++--- 4 files changed, 26 insertions(+), 25 deletions(-) diff --git a/lib/awful/titlebar.lua b/lib/awful/titlebar.lua index e6752534..e390e908 100644 --- a/lib/awful/titlebar.lua +++ b/lib/awful/titlebar.lua @@ -511,8 +511,8 @@ end -- value of `args.position`). -- -- If this constructor is called again with the same --- values for `c` and `args.position` as a previous call, the previous titlebar --- will be removed and replaced by the new one. +-- values for the client (`c`) and the titlebar position (`args.position`), +-- the previous titlebar will be removed and replaced by the new one. -- -- awful.titlebar(c) -- awful.titlebar(c, { position = "left" }) @@ -523,15 +523,15 @@ end -- @tparam[opt=font.height*1.5] number args.size The size of the titlebar. Will -- be interpreted as `height` for horizontal titlebars or as `width` for -- vertical titlebars. --- @tparam[opt=top] string args.position Possible values are `top`, --- `left`, `right` and `bottom`. --- @tparam string args.bg_normal --- @tparam string args.bg_focus --- @tparam string args.bgimage_normal --- @tparam string args.bgimage_focus --- @tparam string args.fg_normal --- @tparam string args.fg_focus --- @tparam string args.font +-- @tparam[opt="top"] string args.position Possible values are `"top"`, +-- `"left"`, `"right"` and `"bottom"`. +-- @tparam[opt] string args.bg_normal +-- @tparam[opt] string args.bg_focus +-- @tparam[opt] string args.bgimage_normal +-- @tparam[opt] string args.bgimage_focus +-- @tparam[opt] string args.fg_normal +-- @tparam[opt] string args.fg_focus +-- @tparam[opt] string args.font -- @constructorfct awful.titlebar -- @treturn wibox.drawable The newly created titlebar object. local function new(c, args) @@ -595,8 +595,8 @@ end --- Show the client's titlebar. -- @param c The client whose titlebar is modified --- @param[opt] position The position of the titlebar. Must be one of `left`, --- `right`, `top`, `bottom`. Default is `top`. +-- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`, +-- `"right"`, `"top"`, `"bottom"`. -- @staticfct awful.titlebar.show -- @request client titlebars show granted Called when `awful.titlebar.show` is -- called. @@ -611,8 +611,8 @@ end --- Hide the client's titlebar. -- @param c The client whose titlebar is modified --- @param[opt] position The position of the titlebar. Must be one of `left`, --- `right`, `top`, `bottom`. Default is `top`. +-- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`, +-- `"right"`, `"top"`, `"bottom"`. -- @staticfct awful.titlebar.hide function titlebar.hide(c, position) position = position or "top" @@ -621,8 +621,8 @@ end --- Toggle the client's titlebar, hiding it if it is visible, otherwise showing it. -- @param c The client whose titlebar is modified --- @param[opt] position The position of the titlebar. Must be one of `left`, --- `right`, `top`, `bottom`. Default is `top`. +-- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`, +-- `"right"`, `"top"`, `"bottom"`. -- @staticfct awful.titlebar.toggle -- @request client titlebars toggle granted Called when `awful.titlebar.toggle` is -- called. @@ -702,9 +702,9 @@ end -- -- A button widget displays an image and reacts to -- mouse clicks. Please note that the caller has to make sure that this widget --- gets redrawn when needed by calling the returned widget's `update()` function. +-- gets redrawn when needed by calling the returned widget's `:update()` method. -- The selector function should return a value describing a state. If the value --- is a boolean, either `active` or `inactive` are used. The actual image is +-- is a boolean, either `"active"` or `"inactive"` are used. The actual image is -- 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. -- diff --git a/lib/gears/table.lua b/lib/gears/table.lua index febe005c..b98aa66d 100644 --- a/lib/gears/table.lua +++ b/lib/gears/table.lua @@ -311,7 +311,7 @@ function gtable.iterate(t, filter, start) end end ---- Merge items from one table into another one. +--- Merge items from the source table into the target table. -- -- Note that this only considers the array part of `source` (same semantics -- as `ipairs`). diff --git a/lib/gears/timer.lua b/lib/gears/timer.lua index fce8140a..20653a4b 100644 --- a/lib/gears/timer.lua +++ b/lib/gears/timer.lua @@ -200,7 +200,7 @@ end -- `callback`. -- The timer will run continuously and call `callback` every `timeout` seconds. -- It is stopped when `callback` returns `false`, when `callback` throws an --- error or when `stop` is called on the return value. +-- error or when the `:stop()` method is called on the return value. -- -- @tparam number timeout Timeout in seconds (e.g. 1.5). -- @tparam function callback Function to run. @@ -257,7 +257,7 @@ function timer.run_delayed_calls_now() delayed_calls = {} end ---- Call the given function at the end of the current main loop iteration. +--- 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 -- @staticfct gears.timer.delayed_call diff --git a/objects/client.c b/objects/client.c index 6b8aee90..2ae4b599 100644 --- a/objects/client.c +++ b/objects/client.c @@ -158,7 +158,8 @@ lua_class_t client_class; * @classsignal */ -/** Emitted before `manage`, after `unmanage`, and when clients swap. +/** Emitted before `request::manage`, after `request::unmanage`, + * and when clients swap. * @signal list * @classsignal */ @@ -408,12 +409,12 @@ lua_class_t client_class; * The focused `client` or nil (in case there is none). * * It is not recommended to set the focused client using - * this property. Please use `c:activate{}` instead of + * this property. Please use @{client.activate} instead of * `client.focus = c`. Setting the focus directly bypasses * all the filters and emits fewer signals, which tend to * cause unwanted side effects and make it harder to alter * the code behavior in the future. It usually takes *more* - * code to use this rather than `:activate{}` because all + * code to use this rather than @{client.activate} because all * the boilerplate code (such as `c:raise()`) needs to be * added everywhere. *