From 5f9bd77bd95dadd51c07c2f30fee3b97a10f2b09 Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage Vallee <elv1313@gmail.com>
Date: Sat, 29 Feb 2020 21:08:42 -0500
Subject: [PATCH 1/3] doc: Do not add parentheses arpund property types.

They provide no value.
---
 docs/ldoc.ltp | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp
index 477af6763..f5604eebf 100644
--- a/docs/ldoc.ltp
+++ b/docs/ldoc.ltp
@@ -217,7 +217,7 @@
     </span>
 #   end -- display_inheritance
 #   if item.display_type then
-    <span class="proptype">($(item.display_type))</span>
+    <span class="proptype">$(item.display_type)</span>
 #   end
     <span class="baseclass" $(nowrap)>
 #   if item.inherited then

From 79dd2d731a4c0a4731940ef7f8324ba5a903f764 Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage Vallee <elv1313@gmail.com>
Date: Sat, 29 Feb 2020 21:10:26 -0500
Subject: [PATCH 2/3] doc: Improve the method and function rendering.

It now adds the return type to the signature.
---
 docs/config.ld | 82 ++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 80 insertions(+), 2 deletions(-)

diff --git a/docs/config.ld b/docs/config.ld
index 62699984a..a556bccfc 100644
--- a/docs/config.ld
+++ b/docs/config.ld
@@ -687,7 +687,18 @@ local function render_methods(item)
     return ret .. " " .. wrap_args(item)
 end
 
--- Parse the magic parameters to type concention in something the template eats.
+-- Replace the "|" in alternative types by "or".
+local function pipe_to_or(s)
+    s = s:gsub("|"," <i>or</i> ")
+
+    if s:sub(1,1) == "?" then
+        s = s:gsub("?","nil <i>or</i> ")
+    end
+
+    return s
+end
+
+-- Parse the magic parameters to type in something the template eats.
 local function sanitize_type(item, ldoc)
 
     for parm in ldoc.modules.iter(item.params) do
@@ -698,7 +709,7 @@ local function sanitize_type(item, ldoc)
         t = t:gsub("?","")
 
         -- Add " or " between alternatives
-        t = t:gsub("|"," <i>or</i> ")
+        t = pipe_to_or(t)
 
         -- Fallback.
         t = t == "" and parm or t
@@ -717,6 +728,65 @@ 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
+
+
+-- Add parentheses when there is alternative return types.
+local function generate_return_tuple(item, group, ldoc)
+    local tuple = {}
+
+    for r in group:iter() do
+        local type = item:return_type(r);
+
+        type = pipe_to_or(type)
+
+        if type ~= nil and type ~= "" then
+            tuple[#tuple+1] = type
+        end
+    end
+
+    if #tuple == 1 then
+        return tuple[1]
+    else
+        local ret = "("
+        for i, elem in ldoc.ipairs(tuple) do
+            ret = ret..elem
+
+            if i ~= #tuple then
+                ret = ret..", "
+            end
+        end
+        ret = ret..")"
+
+        return ret
+    end
+end
+
+-- Create a return type string.
+local function sanitize_return_type(item, ldoc)
+
+    local groups = item.retgroups
+
+    item.display_type = ""
+
+    if groups then
+        item.display_type = "<span class='summary_type'> -&gt;&nbsp;"
+
+        for i,group in ldoc.ipairs(groups) do
+            item.display_type = item.display_type .. generate_return_tuple(
+                item,
+                group,
+                ldoc
+            )
+
+            if i ~= #groups then
+                item.display_type = item.display_type  .. " <i>or</i> "
+            end
+        end
+
+        item.display_type = item.display_type .. "</span>"
+    end
+end
+
 local no_prefix = {
     property           = true,
     signal             = true,
@@ -760,6 +830,12 @@ local display_type = {
     rulecomponent      = true,
 }
 
+-- Add the `-> ret_type` annotation.
+local display_return_type = {
+    method    = true,
+    staticfct = true,
+}
+
 -- Show return values.
 local show_return = {
     ["function"]    = true,
@@ -786,6 +862,8 @@ custom_display_name_handler = function(item, default_handler)
     if display_type[item.type] then
         -- Punch a hole in the sandbox and inject the `ldoc` object.
         item.sanitize_type = sanitize_type
+    elseif display_return_type[item.type] then
+        item.sanitize_type = sanitize_return_type
     end
 
     -- LDoc hardcode the "Returns" section for "function" only, fix that.

From d408ec7846b3bb9370ed87cfecaccf3196585d9b Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage Vallee <elv1313@gmail.com>
Date: Sat, 29 Feb 2020 21:16:11 -0500
Subject: [PATCH 3/3] doc: Use a more compact rendering for method return
 types.

---
 docs/config.ld | 2 ++
 docs/ldoc.css  | 2 +-
 docs/ldoc.ltp  | 9 +++++++--
 3 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/docs/config.ld b/docs/config.ld
index a556bccfc..f3b0b1160 100644
--- a/docs/config.ld
+++ b/docs/config.ld
@@ -785,6 +785,8 @@ local function sanitize_return_type(item, ldoc)
 
         item.display_type = item.display_type .. "</span>"
     end
+
+    item.compact_signature = true
 end
 
 local no_prefix = {
diff --git a/docs/ldoc.css b/docs/ldoc.css
index 3fe8a09d2..f87d1fc0c 100644
--- a/docs/ldoc.css
+++ b/docs/ldoc.css
@@ -316,7 +316,7 @@ span.inheritance {
     font-weight: normal;
 }
 
-td.summarytype {
+.summarytype {
     background-color: white;
     color: #a4c7ff;
     font-size: 85%;
diff --git a/docs/ldoc.ltp b/docs/ldoc.ltp
index f5604eebf..3c878cc36 100644
--- a/docs/ldoc.ltp
+++ b/docs/ldoc.ltp
@@ -155,11 +155,16 @@
 #   local dn = display_name(item)
 #   if item.sanitize_type then item.sanitize_type(item, ldoc) end
     <tr>
-#   if item.display_type then
+#   if item.display_type and not item.compact_signature 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>
+      <td class="name" $(nowrap)>
+        <a href="#$(item.name)">$(dn)</a>
+#     if item.display_type and item.compact_signature then
+        <span class="summarytype">$(item.display_type)</span>
+#     end
+      </td>
 #   end
       <td colspan="$(item.inherited and 1 or 2)" class="summary">$(M(item.summary,item))</td>
 #   if item.inherited then