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.
This commit is contained in:
Emmanuel Lepage Vallee
parent
f26642f037
commit
4a6385cf40
|
|
@ -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>
|
||||
|
After Width: | Height: | Size: 3.6 KiB |
|
|
@ -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%;
|
||||
|
|
|
|||
|
|
@ -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))
|
||||
<ul>
|
||||
# local def = item:default_of_param(sublist)
|
||||
<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>
|
||||
# if tp ~= '' then
|
||||
<span class="types">$(tp)</span>
|
||||
<tr$(sublist and ' class="see_also_sublist"' or '')>
|
||||
<td><span class="parameter">$(name)</span></td>
|
||||
<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))
|
||||
# if def == true then
|
||||
(<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
|
||||
</tr>
|
||||
# end
|
||||
# end -- for
|
||||
</ul>
|
||||
</table>
|
||||
# end -- if params
|
||||
|
||||
# if show_return and item.retgroups then local groups = item.retgroups
|
||||
|
|
|
|||
Loading…
Reference in New Issue