awful.rules: Add proper documentation to the extra client properties.

Until now there wasn't much documentation available about how to use
these properties. With the new work on `awful.spawn` that rely more and
more on `awful.rules` integration, it is worth fixing.

This commit add a new documentation section and a future commit will
aggregate them to generate an index.

docs/config.ld

@@ -72,6 +72,8 @@ new_type("callback", "Callback functions prototype", false, "Parameters")
 new_type("rulesources", "Rule sources", false, "param")
 -- Filter functions for the taglist/tasklist/layoutlist
 new_type("filterfunction", "List filters", false)
+-- Extra client properties available only in awful.rules/spawn constructs
+new_type("clientruleproperty", "Extra properties available in awful.rules and awful.spawn", false, "Type")
 
 -- More fitting section names
 kind_names={topic='Documentation', module='Libraries', script='Sample files'}
@@ -135,10 +137,14 @@ file = {
     }
 }
 
+local no_prefix = {
+    property = true, signal = true, clientruleproperty = true
+}
+
 custom_display_name_handler = function(item, default_handler)
 
     -- Remove the "namespace" from the signals and properties
-    if item.type == "property" or item.type == "signal" then
+    if no_prefix[item.type] then
         local name = item.name:match("%.([^.]+)$")
         return name ~= "" and name or item.name
     end

lib/awful/client.lua

@@ -59,6 +59,93 @@ client.property = {}
 client.shape = require("awful.client.shape")
 client.focus = require("awful.client.focus")
 
+--- The client default placement on the screen.
+--
+-- The default config uses:
+--
+--    awful.placement.no_overlap+awful.placement.no_offscreen
+--
+-- @clientruleproperty placement
+-- @see awful.placement
+
+--- When applying the placement, honor the screen padding.
+-- @clientruleproperty honor_padding
+-- @param[opt=true] boolean
+-- @see awful.placement
+
+--- When applying the placement, honor the screen work area.
+--
+-- The workarea is the part of the screen that excludes the bars and docks.
+--
+-- @clientruleproperty honor_workarea
+-- @param[opt=true] boolean
+-- @see awful.placement
+
+--- The client default tag.
+-- @clientruleproperty tag
+-- @param tag
+-- @see tag
+-- @see new_tag
+-- @see tags
+-- @see switch_to_tags
+
+--- The client default tags.
+--
+-- Avoid using the tag and tags properties at the same time, it will cause
+-- issues.
+--
+-- @clientruleproperty tags
+-- @param[opt={tag}] table
+-- @see tag
+-- @see new_tag
+-- @see tags
+-- @see switch_to_tags
+
+--- Create a new tag for this client.
+--
+-- If the value is `true`, the new tag will be named after the client `class`.
+-- If it is a string, it will be the tag name.
+--
+-- If a table is used, all of its properties will be passed to the tag
+-- constructor:
+--
+--    new_tag = {
+--        name     = "My new tag!", -- The tag name.
+--        layout   = awful.layout.suit.max, -- Set the tag layout.
+--        volatile = true, -- Remove the tag when the client is closed.
+--    }
+--
+-- @tparam[opt=false] table|string|boolean new_tag
+-- @clientruleproperty new_tag
+-- @see tag
+-- @see tags
+-- @see switch_to_tags
+
+--- Unselect the current tags and select this client tags.
+-- Note that this property was called `switchtotag` in previous Awesome versions.
+-- @clientruleproperty switch_to_tags
+-- @param[opt=false] boolean
+-- @see tag.selected
+
+--- Define if the client should grab focus by default.
+--
+-- The `request::activate` context for this call is `rules`.
+--
+-- @clientruleproperty focus
+-- @param[opt=false] boolean
+
+--- Should this client have a titlebar by default.
+-- @clientruleproperty titlebars_enabled
+-- @param[opt=false] boolean
+-- @see awful.titlebar
+
+--- A function to call when this client is ready.
+--
+-- It can be useful to set extra properties or perform actions.
+--
+-- @clientruleproperty callback
+-- @see awful.spawn
+
 --- Jump to the given client.
 -- Takes care of focussing the screen, the right tag, etc.
 --

lib/awful/rules.lua

@@ -536,11 +536,6 @@ function rules.extra_properties.geometry(c, _, props)
     c:geometry(new_geo) --TODO use request::geometry
 end
 
---- Create a new tag based on a rule.
--- @tparam client c The client
--- @tparam boolean|function|string value The value.
--- @tparam table props The properties.
--- @treturn tag The new tag
 function rules.high_priority_properties.new_tag(c, value, props)
     local ty = type(value)
     local t = nil

objects/client.c

@@ -108,7 +108,28 @@
 
 /** Client class.
  *
- * @table object
+ * This table allow to add more dynamic properties to the clients. For example,
+ * doing:
+ *
+ *     function awful.client.object.set_my_cool_property(c, value)
+ *         -- Some logic code
+ *         c._my_secret_my_cool_property = value
+ *         c:emit_signal("property::my_cool_property)
+ *     end
+ *
+ *     function awful.client.object.get_my_cool_property()
+ *         return c._my_secret_my_cool_property
+ *     end
+ *
+ * Will add a new "my_cool_property" dyanmic property to all client. These
+ * methods will be called when an user does `c.my_cool_property = "something"`
+ * or set them in `awdul.rules`.
+ *
+ * Note that doing this isn't required to set random properties to the client,
+ * it is only useful when setting or getting these properties require code to
+ * executed.
+ *
+ * @table awful.object
  */
 
 /** When a client gains focus.