diff --git a/lib/awful/tag.lua b/lib/awful/tag.lua
index 6ad36e905..bb628bf62 100644
--- a/lib/awful/tag.lua
+++ b/lib/awful/tag.lua
@@ -349,7 +349,7 @@ function tag.find_fallback(screen, invalids)
     end
 end
 
---- When all clients are removed from the tag.
+--- Emitted when all clients are removed from the tag.
 -- @signal cleared
 -- @see clear
 
@@ -1841,20 +1841,25 @@ capi.client.connect_signal("untagged", client_untagged)
 capi.client.connect_signal("tagged", client_tagged)
 capi.tag.connect_signal("request::select", tag.object.view_only)
 
---- True when a tagged client is urgent
+--- Emitted when the number of urgent clients on this tag changes.
 -- @signal property::urgent
+-- @param boolean `true` if there is at least one urgent client on the tag.
 -- @see client.urgent
 
---- The number of urgent tagged clients
+--- Emitted when the number of urgent clients on this tag changes.
 -- @signal property::urgent_count
+-- @param integer The number of urgent clients on the tag.
 -- @see client.urgent
 
 --- Emitted when a screen is removed.
+--
 -- This can be used to salvage existing tags by moving them to a new
--- screen (or creating a virtual screen). By default, there is no
--- handler for this request. The tags will be deleted. To prevent
--- this, an handler for this request must simply set a new screen
+-- screen (or creating a virtual screen).
+--
+-- By default, there is no handler for this request and the tags will be deleted.
+-- To prevent this, an handler for this request must simply set a new screen
 -- for the tag.
+--
 -- @signal request::screen
 -- @tparam string context Why it was called.
 
diff --git a/objects/tag.c b/objects/tag.c
index f41ce6545..24b8db6b9 100644
--- a/objects/tag.c
+++ b/objects/tag.c
@@ -205,7 +205,7 @@
 
 lua_class_t tag_class;
 
-/** When a tag requests to be selected.
+/** Emitted when a tag requests to be selected.
  * @signal request::select
  * @tparam string context The reason why it was called.
  * @request tag select ewmh granted When the client request to be moved to a
@@ -240,12 +240,12 @@ lua_class_t tag_class;
  * @tparam table hints A, currently empty, table with hints.
  */
 
-/** When a client gets tagged with this tag.
+/** Emitted when a client gets tagged with this tag.
  * @signal tagged
  * @tparam client c The tagged client.
  */
 
-/** When a client gets untagged with this tag.
+/** Emitted when a client gets untagged with this tag.
  * @signal untagged
  * @tparam client c The untagged client.
  */