Add some documentation to gears.timer

It feels weird to document the signals like this, but apparently that is the way
this needs to be done.

Signed-off-by: Uli Schlachter <psychon@znc.in>

lib/gears/timer.lua

@@ -28,6 +28,12 @@ local object = require("gears.object")
 --   started.
 -- @table timer
 
+--- When the timer is started.
+-- @signal start
+
+--- When the timer is stopped.
+-- @signal stop
+
 local timer = { mt = {} }
 
 --- Start the timer.
@@ -59,6 +65,8 @@ function timer:stop()
 end
 
 --- Restart the timer.
+-- This is equivalent to stopping the timer if it is running and then starting
+-- it.
 function timer:again()
     if self.data.source_id ~= nil then
         self:stop()
@@ -113,6 +121,7 @@ end
 -- callback function causes an error, no more calls are done.
 -- @tparam number timeout Timeout in seconds (e.g. 1.5).
 -- @tparam function callback Function to run.
+-- @treturn timer The timer object that was set up.
 -- @see timer.weak_start_new
 function timer.start_new(timeout, callback)
     local t = timer.new({ timeout = timeout })
@@ -135,6 +144,7 @@ end
 -- will automatically be stopped.
 -- @tparam number timeout Timeout in seconds (e.g. 1.5).
 -- @tparam function callback Function to start.
+-- @treturn timer The timer object that was set up.
 -- @see timer.start_new
 function timer.weak_start_new(timeout, callback)
     local indirection = setmetatable({}, { __mode = "v" })