doc: Add missing C-object documentation and fix some papercuts.

Ref: https://github.com/awesomeWM/awesome/issues/1373

docs/common/cobject.ldoc

@@ -0,0 +1,24 @@
+*/
+
+/** Disconnect from a signal.
+ * @tparam string name The name of the signal.
+ * @tparam function func The callback that should be disconnected.
+ * @function disconnect_signal
+ */
+
+/** Emit a signal.
+ *
+ * @tparam string name The name of the signal.
+ * @param ... Extra arguments for the callback functions. Each connected
+ *   function receives the object as first argument and then any extra
+ *   arguments that are given to emit_signal().
+ * @function emit_signal
+ */
+
+/** Connect to a signal.
+ * @tparam string name The name of the signal.
+ * @tparam function func The callback to call when the signal is emitted.
+ * @function connect_signal
+ */
+
+/*

docs/common/object.ldoc

@@ -1,28 +1,30 @@
 
---- Disconnect to a signal.
--- @tparam string name The name of the signal
--- @tparam function func The callback that should be disconnected
+--- Disconnect from a signal.
+-- @tparam string name The name of the signal.
+-- @tparam function func The callback that should be disconnected.
 -- @function disconnect_signal
 
 --- Emit a signal.
 --
--- @tparam string name The name of the signal
+-- @tparam string name The name of the signal.
 -- @param ... Extra arguments for the callback functions. Each connected
---   function receives the object as first argument and then any extra arguments
---   that are given to emit_signal()
+--   function receives the object as first argument and then any extra
+--   arguments that are given to emit_signal().
 -- @function emit_signal
 
 --- Connect to a signal.
--- @tparam string name The name of the signal
--- @tparam function func The callback to call when the signal is emitted
+-- @tparam string name The name of the signal.
+-- @tparam function func The callback to call when the signal is emitted.
 -- @function connect_signal
 
---- Connect to a signal weakly. This allows the callback function to be garbage
--- collected and automatically disconnects the signal when that happens.
+--- Connect to a signal weakly.
+--
+-- This allows the callback function to be garbage collected and
+-- automatically disconnects the signal when that happens.
 --
 -- **Warning:**
 -- Only use this function if you really, really, really know what you
 -- are doing.
--- @tparam string name The name of the signal
--- @tparam function func The callback to call when the signal is emitted
+-- @tparam string name The name of the signal.
+-- @tparam function func The callback to call when the signal is emitted.
 -- @function weak_connect_signal

lib/awful/wibox.lua

@@ -1,5 +1,7 @@
 ---------------------------------------------------------------------------
---- This module is deprecated and has been renamed `awful.wibar`
+--- This module is deprecated and has been renamed to `awful.wibar`
+--
+-- This only deprecates `awful.wibox`, but not @{wibox}.
 --
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2016 Emmanuel Lepage Vallee

lib/wibox/layout/align.lua

@@ -309,6 +309,8 @@ function align.vertical(top, middle, bottom)
     return ret
 end
 
+--@DOC_fixed_COMMON@
+
 --@DOC_widget_COMMON@
 
 --@DOC_object_COMMON@

lib/wibox/layout/fixed.lua

@@ -14,8 +14,6 @@ local gtable = require("gears.table")
 
 local fixed = {}
 
---@DOC_fixed_COMMON@
-
 -- Layout a fixed layout. Each widget gets just the space it asks for.
 -- @param context The context in which we are drawn.
 -- @param width The available width.
@@ -353,6 +351,8 @@ function fixed:get_spacing()
     return self._private.spacing or 0
 end
 
+--@DOC_fixed_COMMON@
+
 --@DOC_widget_COMMON@
 
 --@DOC_object_COMMON@

objects/button.c

@@ -179,4 +179,6 @@ button_class_setup(lua_State *L)
                             (lua_class_propfunc_t) luaA_button_set_modifiers);
 }
 
+/* @DOC_cobject_COMMON@ */
+
 // vim: filetype=c:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

objects/client.c

@@ -371,7 +371,26 @@
  */
 
 /**
- * The client icon.
+ * The client icon as a surface.
+ *
+ * This property holds the client icon closest to the size configured via
+ * @{awesome.set_preferred_icon_size}.
+ *
+ * It is not a path or an "real" file. Rather, it is already a bitmap surface.
+ *
+ * Typically you would want to use @{awful.widget.clienticon} to get this as a
+ * widget.
+ *
+ * Working with icons is tricky because their surfaces do not use reference
+ * counting correctly. If `gears.surface(c.icon)` is called multiple time on
+ * the same icon, it will cause a double-free error and Awesome will crash. To
+ * get a copy of the icon, you can use:
+ *
+ *     local s = gears.surface(c.icon)
+ *     local img = cairo.ImageSurface.create(cairo.Format.ARGB32, s:get_width(), s:get_height())
+ *     local cr  = cairo.Context(img)
+ *     cr:set_source_surface(s, 0, 0)
+ *     cr:paint()
  *
  * **Signal:**
  *
@@ -379,6 +398,7 @@
  *
  * @property icon
  * @param surface
+ * @usage local ib = wibox.widget.imagebox(c.icon)
  */
 
 /**
@@ -3787,4 +3807,6 @@ client_class_setup(lua_State *L)
                             NULL);
 }
 
+/* @DOC_cobject_COMMON@ */
+
 // vim: filetype=c:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

objects/key.c

@@ -374,4 +374,6 @@ key_class_setup(lua_State *L)
                             (lua_class_propfunc_t) luaA_key_set_modifiers);
 }
 
+/* @DOC_cobject_COMMON@ */
+
 // vim: filetype=c:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

objects/screen.c

@@ -117,14 +117,34 @@
  */
 
 /**
- * The screen number.
+ * The internal screen number.
  *
- * An integer greater than 1 and smaller than `screen.count()`. Please note that
- * the screen order isn't always mirroring the screen logical position.
+ * * The indeces are a continuous sequence from 1 to `screen.count()`.
+ * * It is **NOT** related to the actual screen position relative to each
+ *   other.
+ * * 1 is **NOT** necessarily the primary screen.
+ * * When screens are added and removed indices **CAN** change.
+ *
+ * If you really want to keep an array of screens you should use something
+ * along:
+ *
+ *     local myscreens = setmetatable({}. {__mode="k"})
+ *     myscreens[ screen[1] ] = "mydata"
+ *
+ * But it might be a better option to simply store the data directly in the
+ * screen object as:
+ *
+ *     screen[1].mydata = "mydata"
+ *
+ * Remember that screens are also objects, so if you only want to store a simple
+ * property, you can do it directly:
+ *
+ *     screen[1].answer = 42
  *
  * **Immutable:** true
  * @property index
  * @param integer
+ * @see screen
  */
 
 /**
@@ -1318,4 +1338,6 @@ screen_class_setup(lua_State *L)
                             NULL);
 }
 
+/* @DOC_cobject_COMMON@ */
+
 // vim: filetype=c:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

objects/tag.c

@@ -578,4 +578,6 @@ tag_class_setup(lua_State *L)
                             (lua_class_propfunc_t) luaA_tag_set_activated);
 }
 
+/* @DOC_cobject_COMMON@ */
+
 // vim: filetype=c:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80