diff --git a/lib/awful/ewmh.lua b/lib/awful/ewmh.lua
index e137785b..e02fe817 100644
--- a/lib/awful/ewmh.lua
+++ b/lib/awful/ewmh.lua
@@ -157,6 +157,8 @@ end
 --
 -- This sets the focus only if the client is visible.
 --
+-- It is the default signal handler for `request::activate` on a `client`.
+--
 -- @client c A client to use
 -- @tparam string context The context where this signal was used.
 -- @tparam[opt] table hints A table with additional hints:
diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua
index 470447e5..70c36f97 100644
--- a/lib/awful/tag.lua
+++ b/lib/awful/tag.lua
@@ -706,8 +706,8 @@ local function attached_connect_signal_screen(screen, sig, func)
     end)
 end
 
---- Add a signal to all attached tag and all tag that will be attached in the
--- future. When a tag is detach from the screen, its signal is removed.
+--- Add a signal to all attached tags and all tags that will be attached in the
+-- future. When a tag is detached from the screen, its signal is removed.
 -- @param screen The screen concerned, or all if nil.
 function tag.attached_connect_signal(screen, ...)
     if screen then
diff --git a/objects/client.c b/objects/client.c
index c88d7203..eb50c08c 100644
--- a/objects/client.c
+++ b/objects/client.c
@@ -91,8 +91,8 @@
  * @field transient_for The client the window is transient for.
  * @field group_window Window identification unique to a group of windows.
  * @field leader_window Identification unique to windows spawned by the same command.
- * @field size_hints A table with size hints of the client: user_position,
- *   user_size, program_position, program_size, etc.
+ * @field size_hints A table with size hints of the client: `user_position`,
+ *   `user_size`, `program_position`, `program_size`, etc.
  * @field sticky Set the client sticky, i.e. available on all tags.
  * @field modal Indicate if the client is modal.
  * @field focusable True if the client can receive the input focus.
@@ -458,7 +458,7 @@ client_focus_refresh(void)
             xwindow_takefocus(c->window);
     }
 
-    /* If nothing has the focused or the currently focused client doesn't want
+    /* If nothing has the focus or the currently focused client does not want
      * us to focus it, this sets the focus to the root window. This makes sure
      * the previously focused client actually gets unfocused. Alternatively, the
      * new client gets the input focus.
@@ -1935,8 +1935,8 @@ HANDLE_TITLEBAR(left, CLIENT_TITLEBAR_LEFT)
 
 /** Return or set client geometry.
  *
- * @param arg1 A table with new coordinates, or none.
- * @return A table with client coordinates.
+ * @tparam table|nil geo A table with new coordinates, or nil.
+ * @treturn table A table with client geometry and coordinates.
  * @function geometry
  */
 static int
@@ -2924,8 +2924,13 @@ client_class_setup(lua_State *L)
      * @signal property::y
      */
     signal_add(&client_class.signals, "property::y");
-    /**
+    /** When a client should get activated (focused and/or raised).
+     *
+     * Default implementation: `awful.ewmh.activate`.
      * @signal request::activate
+     * @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?
      */
     signal_add(&client_class.signals, "request::activate");
     /**
diff --git a/objects/drawable.c b/objects/drawable.c
index dff780ec..a702efbe 100644
--- a/objects/drawable.c
+++ b/objects/drawable.c
@@ -144,7 +144,7 @@ luaA_drawable_refresh(lua_State *L)
 
 /** Get drawable geometry. The geometry consists of x, y, width and height.
  *
- * @return A table with drawable coordinates and geometry.
+ * @treturn table A table with drawable coordinates and geometry.
  * @function geometry
  */
 static int