diff --git a/lib/gears/debug.lua b/lib/gears/debug.lua
index 8d7b2da0..fb4d03e5 100644
--- a/lib/gears/debug.lua
+++ b/lib/gears/debug.lua
@@ -75,6 +75,10 @@ end
 
 local displayed_deprecations = {}
 --- Display a deprecation notice, but only once per traceback.
+--
+-- This function also emits the `debug::deprecate` signal on the `awesome`
+-- global object.
+--
 -- @param[opt] see The message to a new method / function to use.
 -- @tparam table args Extra arguments
 -- @tparam boolean args.raw Print the message as-is without the automatic context
@@ -108,6 +112,10 @@ function debug.deprecate(see, args)
         end
     end
     debug.print_warning(msg .. ".\n" .. tb)
+
+    if awesome then
+        awesome.emit_signal("debug::deprecation", msg, see, args)
+    end
 end
 
 --- Create a class proxy with deprecation messages.
diff --git a/luaa.c b/luaa.c
index 28b8aa3e..2bd5e304 100644
--- a/luaa.c
+++ b/luaa.c
@@ -88,8 +88,10 @@ extern const struct luaL_Reg awesome_mouse_meta[];
 
 /** A deprecated Lua function was called.
  *
- * @param hint String with a hint on what to use instead of the
+ * @tparam string hint String with a hint on what to use instead of the
  * deprecated functionality.
+ * @tparam[opt=nil] string|nil see The name of the newer API
+ * @tparam[opt=nil] table|nil args The name of the newer API
  * @signal debug::deprecation
  */