doc: fix signals (#1455)

- rule reordering was mentioned twice in the NEWS
- fix all shown luadoc errors
- add missing descriptions for signals in module "awesome"

docs/89-NEWS.md

@@ -144,10 +144,6 @@ following ones have been added:
 * The `focus` is now going through the focus filters instead of being applied
   as-is (see the focus filter section).
 
-Rules execution has been re-ordered to minimize the race conditions (one rule
-affecting the outcome of another). This may create a slightly different
-behavior for some users, but is usually considered to be an improvement.
-
 #### User rules
 
 It is now possible to register new rules by adding them to some `awful.rules`

lib/awful/mouse/init.lua

@@ -298,7 +298,6 @@ end
 -- @treturn table The list of widgets.The first element is the biggest
 -- container while the last is the topmost widget. The table contains *x*, *y*,
 -- *width*, *height* and *widget*.
--- @see wibox.find_widgets
 
 function mouse.object.get_current_widgets()
     local w = mouse.object.get_current_wibox()
@@ -321,7 +320,6 @@ end
 -- @property current_widget
 -- @tparam widget|nil widget The widget
 -- @treturn ?widget The widget
--- @see wibox.find_widgets
 -- @see current_widget_geometry
 
 function mouse.object.get_current_widget()

lib/awful/widget/prompt.lua

@@ -57,7 +57,7 @@ end
 --
 -- @param args Arguments table. "prompt" is the prompt to use.
 -- @return A launcher widget.
--- @name awful.widget.prompt
+-- @function awful.widget.prompt
 function widgetprompt.new(args)
     args = args or {}
     local widget = textbox()

lib/gears/timer.lua

@@ -185,8 +185,8 @@ end
 -- @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 gears.timer.start_new
+-- @see gears.timer.weak_start_new
 function timer.start_new(timeout, callback)
     local t = timer.new({ timeout = timeout })
     t:connect_signal("timeout", function()
@@ -200,15 +200,15 @@ function timer.start_new(timeout, callback)
 end
 
 --- Create a timeout for calling some callback function.
--- This function is almost identical to `timer.start_new`. The only difference
+-- This function is almost identical to `gears.timer.start_new`. The only difference
 -- is that this does not prevent the callback function from being garbage
 -- collected. After the callback function was collected, the timer returned
 -- 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 gears.timer.weak_start_new
+-- @see gears.timer.start_new
 function timer.weak_start_new(timeout, callback)
     local indirection = setmetatable({}, { __mode = "v" })
     indirection.callback = callback

luaa.c

@@ -67,51 +67,94 @@ extern const struct luaL_Reg awesome_root_lib[];
 extern const struct luaL_Reg awesome_mouse_methods[];
 extern const struct luaL_Reg awesome_mouse_meta[];
 
-/** A call into the lua code aborted with an error
+/** A call into the Lua code aborted with an error.
+ *
+ * This signal is used in the example configuration, @{05-awesomerc.md},
+ * to let a notification box pop up.
+ * @param err Table with the error object, can be converted to a string with
+ * `tostring(err)`.
  * @signal debug::error
  */
 
-/** A deprecated lua function was called
+/** A deprecated Lua function was called.
+ *
+ * @param hint String with a hint on what to use instead of the
+ * deprecated functionality.
  * @signal debug::deprecation
  */
 
-/** An invalid key was read from an object, for example `c.foo`
+/** An invalid key was read from an object.
+ *
+ * This can happen if `foo` in an `c.foo` access does not exist.
+ * @param unknown1 Class?
+ * @param unknown2 Key?
  * @signal debug::index::miss
  */
 
-/** An invalid key was written to an object, for example `c.foo = "bar"`
+/** An invalid key was written to an object.
+ *
+ * This can happen if `foo` in an `c.foo = "bar"` assignment doesn't exist.
+ * @param unknown1 Class?
+ * @param unknown2 Key?
+ * @param unknown3 Value?
  * @signal debug::newindex::miss
  */
 
-/**
+/** The systray should be updated.
+ *
+ * This signal is used in `wibox.widget.systray`.
  * @signal systray::update
  */
 
-/**
+/** The wallpaper has just been changed. This signal is used for
+ *
+ * pseudo-transparency in `wibox.drawable` if no composite manager is
+ * running.
  * @signal wallpaper_changed
  */
 
-/**
+/** Keyboard map has changed.
+ *
+ * This signal is sent after the new keymap has been loaded. It is used in
+ * `awful.widget.keyboardlayout` to redraw the layout.
  * @signal xkb::map_changed
  */
 
-/**
+/** Keyboard group has changed.
- * @signal xkb::group_changed
+ *
+ * It's used in `awful.widget.keyboardlayout` to redraw the layout.
+ * @param group Integer containing the changed group
+ * @signal xkb::group_changed.
  */
 
-/**
+/** Refresh.
+ *
+ * This signal is emitted as a kind of idle signal in the event loop.
+ * One example usage is in `gears.timer` to executed delayed calls.
  * @signal refresh
  */
 
-/**
+/** Awesome is about to enter the event loop.
+ *
+ * This means all initialization has been done.
  * @signal startup
  */
 
-/**
+/** Awesome is exiting / about to restart.
+ *
+ * This signal is emitted in the `atexit` handler as well when awesome
+ * restarts.
+ * @param reason_restart Boolean value is true if the signal was sent
+ * because of a restart.
  * @signal exit
  */
 
-/**
+/** The output status of a screen has changed.
+ *
+ * @param output String containing which output has changed.
+ * @param connection_state String containing the connection status of
+ * the output: It will be either "Connected", "Disconnected" or
+ * "Unknown".
  * @signal screen::change
  */
 

objects/screen.c

@@ -155,7 +155,6 @@
  *
  * @property workarea
  * @see client.struts
- * @see wibox.struts
  * @param table
  * @tfield integer table.x The horizontal position
  * @tfield integer table.y The vertical position