From 3e3a298a3332ab6e8b458a179701b0fc2afeb61c Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage Vallee <elv1313@gmail.com>
Date: Sat, 8 Jun 2019 00:35:02 -0400
Subject: [PATCH] doc: Shape the methods and functions arguments in the
 summary.

Given the full prototype can be quite long with all the optional
argument definition, better help the eyes focus on the important
part.
---
 docs/config.ld | 25 +++++++++++++++++++++----
 docs/ldoc.css  |  6 ++++++
 2 files changed, 27 insertions(+), 4 deletions(-)

diff --git a/docs/config.ld b/docs/config.ld
index 7ad68762..64bf0cb2 100644
--- a/docs/config.ld
+++ b/docs/config.ld
@@ -165,6 +165,21 @@ file = {
     }
 }
 
+-- Wrap the module name for the CSS highlight.
+local function wrap_modname(str, item)
+    if (not item.module) or str:sub(1, #item.module.name+1) ~= item.module.name.."." then return str end
+
+    return "<span class='function_modname'>"..item.module.name..".</span>"
+        .. str:sub(#item.module.name+2, 9999)
+end
+
+-- Wrap the arguments for the CSS highlight.
+local function wrap_args(item)
+    if not item.args then return "" end
+    return "<span class='function_args'>"..item.args.."</span>"
+end
+
+
 -- Mimics the ldoc built-in method style, but better.
 --
 -- This custom renderer exists because using ldoc built-in method detection
@@ -177,7 +192,7 @@ local function render_methods(item)
         ret = ":"..ret
     end
 
-    return ret .. (item.args and " "..item.args or "")
+    return ret .. " " .. wrap_args(item)
 end
 
 -- Parse the magic parameters to type concention in something the template eats.
@@ -210,7 +225,6 @@ local function sanitize_type(item, ldoc)
     -- 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,
@@ -284,7 +298,7 @@ custom_display_name_handler = function(item, default_handler)
     end
 
     if item.type == "method" then
-        return render_methods(item)
+        ret = render_methods(item)
     end
 
 
@@ -300,9 +314,12 @@ custom_display_name_handler = function(item, default_handler)
 
     -- It isn't there by default.
     if add_args[item.type] then
-        ret = ret .. " " .. item.args
+        ret = ret .. " " .. wrap_args(item)
     end
 
+    -- Beautify.
+    ret = wrap_modname(ret, item)
+
     return ret
 end
 
diff --git a/docs/ldoc.css b/docs/ldoc.css
index 4a4412e4..2355bf2c 100644
--- a/docs/ldoc.css
+++ b/docs/ldoc.css
@@ -309,6 +309,12 @@ td.summarytype {
     text-align: right;
 }
 
+table.function_list .function_args /*.function_modname*/ {
+    color: #94b1ff;
+    text-decoration: underline;
+    text-decoration-color: #bbd3ff;
+}
+
 dl.function {
     margin-right: 15px;
     margin-left: 15px;