diff --git a/lib/awful/rules.lua b/lib/awful/rules.lua
index d45a81e79..10a7bb86d 100644
--- a/lib/awful/rules.lua
+++ b/lib/awful/rules.lua
@@ -1,5 +1,8 @@
 ---------------------------------------------------------------------------
---- Apply rules to clients at startup.
+--- Rules for clients.
+--
+-- This module applies @{rules} to clients during startup (via @{client.manage},
+-- but its functions can be used for client matching in general.
 --
 -- All existing `client` properties can be used in rules. It is also possible
 -- to add random properties that will be later accessible as `c.property_name`
diff --git a/objects/client.c b/objects/client.c
index 0ec571f92..ed92aeb35 100644
--- a/objects/client.c
+++ b/objects/client.c
@@ -125,7 +125,7 @@
  * @signal .swapped
  */
 
-/**
+/** When a new client appears and gets managed by Awesome.
  * @signal .manage
  */