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/objects/client.c b/objects/client.c
index 20931b15..ea834b97 100644
--- a/objects/client.c
+++ b/objects/client.c
@@ -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");
     /**