doc: Add support for property types to ldoc.

Rather that abusing of how the arguments are displayed to convey the
type, add native support.

It still uses the @param for the doc, so this doesn't cause a million
little noisy changes, but the rendered HTML now have a real section for
the type. This is added to both the summary and the expanded description.

Additionally, if the type has a description string, a second is added.

docs/config.ld

@@ -60,9 +60,9 @@ new_type("function", "Functions", false, "Parameters")
 -- @function and its implicit cousin to be banned in the CI.
 new_type("staticfct", "Static module functions", false, "Parameters")
 -- Documentation for objects properties
-new_type("property", "Object properties", false, "Type")
+new_type("property", "Object properties", false, "Type constraints")
 -- Documentation for objects deprecated properties
-new_type("deprecatedproperty", "Deprecated object properties", false, "Type")
+new_type("deprecatedproperty", "Deprecated object properties", false, "Type constraints")
 -- Use a custom type for the methods to bypass the faulty ldoc built-in detection.
 -- (yes, the space after Methods *is* on purpose to avoid clashing with ldoc
 --  internal "methods" concept)
@@ -72,7 +72,7 @@ new_type("signal", "Signals", false, "Arguments")
 -- New type for signals connections
 new_type("signalhandler", "Request handlers", false, "Arguments")
 -- Allow objects to define a set of beautiful properties affecting them
-new_type("beautiful", "Theme variables", false, "Type")
+new_type("beautiful", "Theme variables", false, "Type constraints")
 -- Put deprecated methods in their own section
 new_type("deprecated", "Deprecated functions", false, "Parameters")
 -- For the legacy stateless layout related functions
@@ -180,6 +180,37 @@ local function render_methods(item)
     return ret .. (item.args and " "..item.args or "")
 end
 
+-- Parse the magic parameters to type concention in something the template eats.
+local function sanitize_type(item, ldoc)
+
+    for parm in ldoc.modules.iter(item.params) do
+        local t = item:type_of_param(parm)
+
+        -- Remove the value.
+        t = t:gsub("(\\[[^\\]]])","")
+        t = t:gsub("?","")
+
+        -- Add " or " between alternatives
+        t = t:gsub("|"," <i>or</i> ")
+
+        -- Fallback.
+        t = t == "" and parm or t
+        t = t == "" and "N/A" or t
+
+        item.display_type = "<span class='summary_type'>"..t.."</span>"
+
+        -- There is no value in repeating the type a second time.
+        if item.params.map[parm] == "" then
+            item.hide_params = true
+        end
+
+        if t ~= "N/A" then return end
+    end
+
+    -- It has to be set, otherwise the table will have different col count.
+    item.display_type = "<span class='summary_type'>N/A</span>"
+end
+
 local no_prefix = {
     property = true, signal = true, clientruleproperty = true,
     deprecatedproperty = true,
@@ -208,9 +239,23 @@ local add_args = {
     staticfct      = true,
 }
 
+-- Add a type column to the summary and type field in the description.
+local display_type = {
+    property           = true,
+    beautiful          = true,
+    field              = true,
+    deprecatedproperty = true,
+}
+
 custom_display_name_handler = function(item, default_handler)
     local ret = default_handler(item)
 
+    -- Edit the input so the template is notified.
+    if display_type[item.type] then
+        -- Punch a hole in the sandbox and inject the `ldoc` object.
+        item.sanitize_type = sanitize_type
+    end
+
     -- Remove the "namespace" from the signals and properties
     if no_prefix[item.type] then
         local name = item.name:match("%.([^.]+)$")

docs/ldoc.css

@@ -290,6 +290,25 @@ table.module_list td.summary, table.function_list td.summary {
     border-left-width: 0px;
 }
 
+table.function_list td.shortname {
+    background-color: white;
+    border-right-width: 0px;
+}
+
+.proptype {
+    padding-right: 20px;
+    float: right;
+}
+
+td.summarytype {
+    background-color: white;
+    color: #a4c7ff;
+    font-size: 85%;
+    border-left: none;
+    border-right: none;
+    text-align: right;
+}
+
 dl.function {
     margin-right: 15px;
     margin-left: 15px;

docs/ldoc.ltp

@@ -127,8 +127,15 @@
 <h2><a href="#$(no_spaces(kind))">$(kind)</a></h2>
 <table class="function_list">
 #  for item in items() do
+#   local dn = display_name(item)
+#   if item.sanitize_type then item.sanitize_type(item, ldoc) end
 	<tr>
-	<td class="name" $(nowrap)><a href="#$(item.name)">$(display_name(item))</a></td>
+#   if item.display_type then
+	<td class="shortname" $(nowrap)><a href="#$(item.name)">$(dn)</a></td>
+	<td class="summarytype" nowrap>$(item.display_type)</td>
+#   else
+	<td class="name" $(nowrap)><a href="#$(item.name)">$(dn)</a></td>
+#   end
 	<td class="summary">$(M(item.summary,item))</td>
 	</tr>
 #  end -- for items
@@ -165,6 +172,9 @@
     <dt>
     <a name = "$(item.name)"></a>
     <strong>$(display_name(item))</strong>
+#   if item.display_type then
+    <span class="proptype">($(item.display_type))</span>
+#   end
 #   if ldoc.prettify_files and ldoc.is_file_prettified[item.module.file.filename] then
     <a style="float:right;" href="$(ldoc.source_ref(item))">line $(item.lineno)</a>
 #  end
@@ -187,7 +197,7 @@
 #    end -- iter tags
 #   end
 
-#  if show_parms and item.params and #item.params > 0 then
+#  if show_parms and item.params and #item.params > 0 and not item.hide_params then
 #    local subnames = module.kinds:type_of(item).subnames
 #    if subnames then
     <h3>$(subnames):</h3>