Minor doc and code style fixes

Closes https://github.com/awesomeWM/awesome/pull/1215.

awesomerc.lua

@@ -394,7 +394,7 @@ for i = 1, 9 do
                         end
                   end,
                   {description = "view tag #"..i, group = "tag"}),
-        -- Toggle tag.
+        -- Toggle tag display.
         awful.key({ modkey, "Control" }, "#" .. i + 9,
                   function ()
                       local screen = awful.screen.focused()
@@ -555,7 +555,7 @@ client.connect_signal("request::titlebars", function(c)
     }
 end)
 
--- Enable sloppy focus
+-- Enable sloppy focus, so that focus follows mouse.
 client.connect_signal("mouse::enter", function(c)
     if awful.layout.get(c.screen) ~= awful.layout.suit.magnifier
         and awful.client.focus.filter(c) then

lib/awful/client.lua

@@ -900,19 +900,19 @@ function client.setwfact(wfact, c)
     t:emit_signal("property::windowfact")
 end
 
---- Increment a client's window factor
+--- Change window factor of a client.
 --
 -- @legacylayout awful.client.incwfact
--- @param add amount to increase the client's window
+-- @tparam number add Amount to increase/decrease the client's window factor.
+--   Should be between `-current_window_factor` and something close to
+--   infinite.  The normalisation then ensures that the sum of all factors is 1.
 -- @client c the client
 function client.incwfact(add, c)
     c = c or capi.client.focus
     if not c then return end
 
     local t = c.screen.selected_tag
-
     local w = client.idx(c)
-
     local data = t.windowfact or {}
     local colfact = data[w.col] or {}
     local curr = colfact[w.idx] or 1

lib/awful/mouse/resize.lua

@@ -55,14 +55,14 @@ function module.set_mode(m)
     mode = m
 end
 
---- Add a initialization callback.
--- This callback will be executed before the mouse grabbing start
+--- Add an initialization callback.
+-- 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
 function module.add_enter_callback(cb, context)
-    context = context or  "other"
-    callbacks.enter[context] =  callbacks.enter[context] or {}
+    context = context or "other"
+    callbacks.enter[context] = callbacks.enter[context] or {}
     table.insert(callbacks.enter[context], cb)
 end
 
@@ -196,7 +196,7 @@ local function handler(_, client, context, args) --luacheck: no unused_args
 
         -- Only resize after the mouse is released, this avoid losing content
         -- in resize sensitive apps such as XTerm or allow external modules
-        -- to implement custom resizing
+        -- to implement custom resizing.
         if args.mode == "after" then
             -- Get the new geometry
             geo = args.placement(client, args)

lib/awful/tag.lua

@@ -1359,7 +1359,9 @@ end
 -- future. When a tag is detached from the screen, its signal is removed.
 --
 -- @function awful.tag.attached_connect_signal
--- @param screen The screen concerned, or all if nil.
+-- @screen The screen concerned, or all if nil.
+-- @tparam[opt] string Signal
+-- @tparam[opt] function Callback
 function tag.attached_connect_signal(screen, ...)
     if screen then
         attached_connect_signal_screen(screen, ...)