doc: Implement review suggetions

Co-authored-by: Aire-One <Aire-One@users.noreply.github.com>

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
+-- values for the client (`c`) and the titlebar position (`args.position`),
--- will be removed and replaced by the new one.
+-- 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`,
+-- @tparam[opt="top"] string args.position Possible values are `"top"`,
--- `left`, `right` and `bottom`.
+-- `"left"`, `"right"` and `"bottom"`.
--- @tparam string args.bg_normal
+-- @tparam[opt] string args.bg_normal
--- @tparam string args.bg_focus
+-- @tparam[opt] string args.bg_focus
--- @tparam string args.bgimage_normal
+-- @tparam[opt] string args.bgimage_normal
--- @tparam string args.bgimage_focus
+-- @tparam[opt] string args.bgimage_focus
--- @tparam string args.fg_normal
+-- @tparam[opt] string args.fg_normal
--- @tparam string args.fg_focus
+-- @tparam[opt] string args.fg_focus
--- @tparam string args.font
+-- @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`,
+-- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`,
---   `right`, `top`, `bottom`. Default is `top`.
+--   `"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`,
+-- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`,
---   `right`, `top`, `bottom`. Default is `top`.
+--   `"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`,
+-- @tparam[opt="top"] string position The position of the titlebar. Must be one of `"left"`,
---   `right`, `top`, `bottom`. Default is `top`.
+--   `"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.
 --

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`).

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

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.
  *