doc: Replace the function argument rendering.

This is an attempt at solving several problems reported by novice
users. The old rendering was very compact and quite fine once you
got used to its, ..., "conventions". But it was also sometime rather
hard to read.

First of all, it abused bold and italic. It also "merged" optional
parameters and parameters with default content. It got worst when
the documentation was spread over mutiple lines.

For property types and constructors with large number of parameters,
it was also quite unreadable.

The new representation, while far from perfect, is less dense and
more explicit. It has a separate column for "optional" using the
new "metadata chip" documentation concept. It is also an aligned
table and correctly renders multi-line documentation.

Finally, it adds a "note" message when the named parameter convention
is used. This way the users looking at the examples will be less
confused.

docs/images/warning_icon.svg

@@ -0,0 +1,84 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="32mm"
+   height="32mm"
+   viewBox="0 0 32 32"
+   version="1.1"
+   id="svg8"
+   inkscape:version="0.92.5 (2060ec1f9f, 2020-04-08)"
+   sodipodi:docname="warning_icon.svg">
+  <defs
+     id="defs2" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="1.979899"
+     inkscape:cx="74.464747"
+     inkscape:cy="-39.991417"
+     inkscape:document-units="mm"
+     inkscape:current-layer="layer1"
+     showgrid="false"
+     showguides="true"
+     inkscape:guide-bbox="true"
+     inkscape:window-width="1916"
+     inkscape:window-height="980"
+     inkscape:window-x="2"
+     inkscape:window-y="32"
+     inkscape:window-maximized="1"
+     fit-margin-top="0"
+     fit-margin-left="0"
+     fit-margin-right="0"
+     fit-margin-bottom="0">
+    <inkscape:grid
+       type="xygrid"
+       id="grid856"
+       originx="-0.056405092"
+       originy="-80.825357" />
+    <sodipodi:guide
+       position="40.835834,95.839799"
+       orientation="0,1"
+       id="guide858"
+       inkscape:locked="false" />
+    <sodipodi:guide
+       position="100.97147,-58.641987"
+       orientation="0,1"
+       id="guide860"
+       inkscape:locked="false" />
+  </sodipodi:namedview>
+  <metadata
+     id="metadata5">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title></dc:title>
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-0.05640609,-184.17464)">
+    <path
+       style="opacity:1;fill:#cdcdcd;fill-opacity:0.94170403;stroke-width:0.04273237"
+       d="m 15.987264,186.03934 c -0.51293,0.002 -1.011107,0.29721 -1.303535,0.87343 L 7.4496946,199.4451 0.19454716,212.01408 c -0.41426919,0.8099 0.11377925,2.28705 1.44206664,2.28967 H 16.02657 30.8287 c 0.832347,0 1.63675,-1.03166 0.995843,-2.34869 l -7.2211,-12.50996 -7.223935,-12.5148 c -0.351606,-0.60004 -0.879318,-0.89253 -1.392244,-0.89096 z m 0.03104,4.53979 c 0.728062,0 1.279641,0.27585 1.654705,0.82752 0.386093,0.55168 0.579079,1.5502 0.579079,2.99559 0,0.50754 -0.02754,1.00954 -0.0827,1.50605 -0.05516,0.48549 -0.126892,1.02062 -0.215143,1.60539 l -1.158243,8.40755 h -1.605051 l -1.075539,-7.76208 c -0.09928,-0.78337 -0.193071,-1.45643 -0.28132,-2.01914 -0.08824,-0.57375 -0.132357,-1.16407 -0.132357,-1.77092 0,-1.31298 0.198563,-2.27287 0.595688,-2.87972 0.408155,-0.60685 0.981789,-0.91024 1.720883,-0.91024 z m 0.03305,16.9475 c 0.71703,0 1.323786,0.24829 1.820192,0.7448 0.496405,0.49651 0.744566,1.10332 0.744566,1.82049 0,0.72822 -0.248161,1.34608 -0.744566,1.85363 -0.496406,0.50754 -1.103162,0.76133 -1.820192,0.76133 -0.728061,0 -1.345802,-0.25379 -1.85324,-0.76133 -0.507436,-0.50755 -0.76109,-1.12541 -0.76109,-1.85363 0,-0.71717 0.253654,-1.32398 0.76109,-1.82049 0.507438,-0.49651 1.125179,-0.7448 1.85324,-0.7448 z"
+       id="path849"
+       inkscape:connector-curvature="0" />
+  </g>
+</svg>

docs/ldoc.css

@@ -25,22 +25,37 @@ hr {
 tt {
     font-family: monospace;
 }
+
 span.parameter {
     font-family: monospace;
     font-weight: bold;
     color: rgb(99, 115, 131);
 }
-span.parameter:after {
+
-    content:":";
+span.optional_param {
+    font-style: italic;
+    color: rgb(143, 166, 230);
 }
-span.types:before {
+
-    content:"(";
+.types {
+    white-space: pre;
 }
-span.types:after {
+
-    content:")";
+td span.types {
+    flex-flow: nowrap;
+    display: inline-flex;
+    width: 100%;
 }
+
 .type {
-    font-weight: bold; font-style:italic
+    flex-basis: auto;
+    font-weight: bold;
+    font-style:italic;
+    pointer-events: none;
+    text-decoration: none;
+    color: #008fee;
+    text-align: center;
+    flex-grow: 1;
 }
 
 p.name {
@@ -51,7 +66,12 @@ kbd,
 p code,
 ol code,
 ul code,
-dd > code {
+dd > code,
+td code,
+span.default_value,
+.see_also_description code,
+.important_box code
+{
     background-color: #eaedf587;
     padding-left: 3px;
     padding-right: 3px;
@@ -161,6 +181,7 @@ dd > code {
     margin-left: 15px;
     margin-bottom: 5px;
     border-bottom: solid 1px #bcd;
+    font-weight: normal;
 }
 
 #content h4 {
@@ -233,8 +254,24 @@ table th, table td {
     padding: 2px;
 }
 
-.see_also, .see_also td {
+.important_box {
+    padding-left: 40px;
+    min-height: 32px;
+    max-width: 640px;
+    vertical-align: middle;
+    background-image: url("images/warning_icon.svg");
+    background-size: 32px 32px;
+    background-repeat: no-repeat;
+    background-position: left center;
+    margin-top: 15px;
+    margin-bottom: 5px;
+    margin-left: 10px;
+}
+
+.see_also, .see_also td, .see_also th {
     border-style: hidden !important;
+    padding-left: 5pt;
+    padding-right: 5pt;
 }
 
 .see_also tr td:nth-of-type(1) {
@@ -247,6 +284,26 @@ table th, table td {
     background-color: #f7fbff;
 }
 
+.see_also tr th {
+    color: rgb(168, 168, 168);
+    padding-top: 15px;
+    padding-bottom: 4px;
+    font-weight: normal;
+    text-decoration: none;
+    font-style:italic;
+    font-size: 85%;
+}
+
+.see_also_description {
+    max-width: 640px;
+}
+
+.see_also_sublist td:nth-of-type(1) {
+    margin-left: 10px;
+    padding-left: 15px;
+    border-left: 1px solid rgb(200, 200, 200) !important;
+}
+
 .widget_list td {
     padding-top: 10px;
     padding-bottom: 10px;
@@ -376,6 +433,14 @@ span.inheritance {
     font-weight: normal;
 }
 
+span.not_applicable {
+    color: rgb(200, 200, 200);
+    font-style:italic;
+    font-size: 85%;
+    text-align: center;
+    display: block;
+}
+
 .summarytype {
     color: #a4c7ff;
     font-size: 85%;

docs/ldoc.ltp

@@ -139,7 +139,7 @@
 # if ldoc.no_summary and module and not ldoc.one then -- bang out the functions on the side
 # for kind, items in module.kinds() do
 #  if not kind:match("^ldoc_skip") then
-<h2>$(kind)dasdasd</h2>
+<h2>$(kind)</h2>
 <ul class="nowrap">
 #  end
 # for item in items() do
@@ -373,35 +373,75 @@
 #    if subnames then
     <h3>$(subnames):</h3>
 #    end
-    <ul>
+#   local has_optional, has_named_call = false, false
+#   for parm in iter(item.params) do
+#     local param,sublist = item:subparam(parm)
+#     has_named_call = has_named_call or (sublist and item.is_named_call)
+#     for p in iter(param) do
+#       local def = item:default_of_param(p)
+#       has_optional = has_optional or (def and def ~= true)
+#     end
+#   end
+#   if has_named_call then
+        <div class="important_box">
+          <b>Note:</b> This $(item.kind) uses named parameters calling convention. It
+          means you call it with $(M('`{}`')) and omit the parantheses. For example,
+          calling this will all default argument would be <code>$(item.name){}</code>.
+          This is a Lua shortcut syntax equivalent to <code>$(item.name)({})</code>.
+          <code>args</code> is only a placeholder name for the "lone table argument"
+          used in named parameters calls.
+        </div>
+#   end
+    <table class="see_also">
+         <tr class="param_header">
+            <th>Name</th>
+            <th></th>
+            <th>Type(s)</th>
+            <th>Description</th>
+#   if has_optional then
+            <th>Default value</th>
+#   end
+         </tr>
 #   for parm in iter(item.params) do
 #     local param,sublist = item:subparam(parm)
 #     if sublist then
-        <li><span class="parameter">$(sublist)</span>$(M(item.params.map[sublist],item))
+#       local def = item:default_of_param(sublist)
-        <ul>
+        <tr>
+           <td><span class="parameter">$(sublist)</span></td>
+           <td>$(def and '<span class="chips">Optional</span>' or '')</td>
+           <td><span class="types"><span class="type">table</span></span></td>
+           <td class="see_also_description">$(M(item.params.map[sublist],item)) </td>
+#      if has_optional then
+#       if def and def ~= true then
+          <td><span class="default_value"><code>$(def)</code></span></td>
+#       elseif def then
+           <td><span class="not_applicable">Undefined</span></td>
+#       else
+           <td><span class="not_applicable" title="This parameter is mandatory">Not applicable</span></td>
+#       end
+#      end
+         </tr>
 #     end
 #     for p in iter(param) do
 #        local name,tp,def = item:display_name_of(p), ldoc.typename(item:type_of_param(p)), item:default_of_param(p)
-        <li><span class="parameter">$(name)</span>
+         <tr$(sublist and ' class="see_also_sublist"' or '')>
-#       if tp ~= '' then
+           <td><span class="parameter">$(name)</span></td>
-            <span class="types">$(tp)</span>
+           <td>$(def and '<span class="chips">Optional</span>' or '')</td>
+           <td><span class="types">$(tp)</span></td>
+           <td class="see_also_description">$(M(item.params.map[p],item))</td>
+#      if has_optional then
+#       if def and def ~= true then
+           <td><span class="default_value"><code>$(def)</code></span></td>
+#       elseif def then
+           <td><span class="not_applicable">Undefined</span></td>
+#       else
+           <td><span class="not_applicable" title="This parameter is mandatory">Not applicable</span></td>
 #       end
-        $(M(item.params.map[p],item))
+#      end
-#       if def == true then
+         </tr>
-         (<em>optional</em>)
-#      elseif def then
-         (<em>default</em> <code>$(def)</code>)
-#       end
-#       if item:readonly(p) then
-          <em>readonly</em>
-#       end
-        </li>
-#     end
-#     if sublist then
-        </li></ul>
 #     end
 #   end -- for
-    </ul>
+        </table>
 #   end -- if params
 
 #  if show_return and item.retgroups then local groups = item.retgroups