screen: Update the documentation

objects/screen.c

@@ -47,14 +47,79 @@
  * The primary screen can be accessed as `screen.primary`.
  * Each screen has a set of properties.
  *
- * @tfield table geometry The screen coordinates. Immutable.
- * @tfield table workarea The screen workarea.
- * @tfield int index The screen number.
- * @tfield table outputs If RANDR information is available, a list of outputs
- *   for this screen and their size in mm.
- * @table screen
  */
 
+ /**
+  * The primary screen.
+  *
+  * @tfield screen primary
+  */
+
+/**
+ * The screen coordinates.
+ *
+ * **Immutable:** true
+ * @property geometry
+ * @param table
+ * @tfield integer table.x The horizontal position
+ * @tfield integer table.y The vertical position
+ * @tfield integer table.width The width
+ * @tfield integer table.height The height
+ */
+
+/**
+ * The 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.
+ *
+ * **Immutable:** true
+ * @property index
+ * @param integer
+ */
+
+/**
+ * If RANDR information is available, a list of outputs
+ *   for this screen and their size in mm.
+ *
+ * Please note that the table content may vary.
+ *
+ * **Signal:**
+ *
+ *  * *property::outputs*
+ *
+ * **Immutable:** true
+ * @property outputs
+ * @param table
+ * @tfield table table.name A table with the screen name as key (like `eDP1` on a laptop)
+ * @tfield integer table.name.mm_width The screen physical width
+ * @tfield integer table.name.mm_height The screen physical height
+ */
+
+/**
+ * The screen workarea.
+ *
+ * The workarea is a subsection of the screen where clients can be placed. It
+ * usually excludes the toolbars (see `awful.wibox`) and dockable clients
+ * (see `client.dockable`) like WindowMaker DockAPP.
+ *
+ * It can be modified be altering the `wibox` or `client` struts.
+ *
+ * **Signal:**
+ *
+ *  * *property::workarea*
+ *
+ * @property workarea
+ * @see client.struts
+ * @see drawin.struts
+ * @param table
+ * @tfield integer table.x The horizontal position
+ * @tfield integer table.y The vertical position
+ * @tfield integer table.width The width
+ * @tfield integer table.height The height
+ */
+
+
 /** Get the number of instances.
  *
  * @return The number of screen objects alive.
@@ -752,17 +817,15 @@ screen_class_setup(lua_State *L)
                             NULL,
                             (lua_class_propfunc_t) luaA_screen_get_workarea,
                             NULL);
-    /**
-     * @signal property::workarea
-     */
+
     signal_add(&screen_class.signals, "property::workarea");
     /**
-     * @signal primary_changed
+     * @signal .primary_changed
      */
     signal_add(&screen_class.signals, "primary_changed");
     /**
      * This signal is emitted when a new screen is added to the current setup.
-     * @signal added
+     * @signal .added
      */
     signal_add(&screen_class.signals, "added");
 }