Consider alternate styling/linking for method argument definitions #574
Description
Method arguments are currently detailed with this markdown (using compute() as an example):
<div>
**Arguments:**
- *graph*: an {{MLGraph}}. The compiled graph to be executed.
- *inputs*: an {{MLNamedArrayBufferViews}}. The resources of inputs. Will be [=MLNamedArrayBufferViews/transfer|transferred=] if there are no validation errors.
- *outputs*: an {{MLNamedArrayBufferViews}}. The pre-allocated resources of required outputs. Will be [=MLNamedArrayBufferViews/transfer|transferred=] if there are no validation errors.
</div>
which renders as:
There are a few other forms used in other specs worth considering to improve maintainability.
Alternative 1: Make args into definitions
A minimal change makes the argument names become definitions which are get automatically linked, to help catch errors.
<div dfn-for="MLContext/compute(graph, inputs, outputs)" dfn-type="argument">
**Arguments:**
- <dfn>graph</dfn>: an {{MLGraph}}. The compiled graph to be executed.
- <dfn>inputs</dfn>: an {{MLNamedArrayBufferViews}}. The resources of inputs. Will be [=MLNamedArrayBufferViews/transfer|transferred=] if there are no validation errors.
- <dfn>outputs</dfn>: an {{MLNamedArrayBufferViews}}. The pre-allocated resources of required outputs. Will be [=MLNamedArrayBufferViews/transfer|transferred=] if there are no validation errors.
</div>
which renders as:
Alternative 2: Style as definition list
Extending the above using a definition list, similar to what is currently done for dictionaries:
**Arguments:**
<dl dfn-for="MLContext/compute(graph, inputs, outputs)" dfn-type="argument">
: <dfn>graph</dfn>
:: an {{MLGraph}}. The compiled graph to be executed.
: <dfn>inputs</dfn>
:: an {{MLNamedArrayBufferViews}}. The resources of inputs. Will be [=MLNamedArrayBufferViews/transfer|transferred=] if there are no validation errors.
: <dfn>outputs</dfn>
:: an {{MLNamedArrayBufferViews}}. The pre-allocated resources of required outputs. Will be [=MLNamedArrayBufferViews/transfer|transferred=] if there are no validation errors.
</dl>
which renders as:
Alternative 3: Auto-generated table
This is a much more radical departure from what the spec has today. The spec source is extremely compact, which eases maintenance. Argument type, nullability, and optionality are filled in by Bikeshed automatically, reducing errors. On the flip side, I personally find the big table ugly.
<pre class=argumentdef for="MLContext/compute(graph, inputs, outputs)">
graph: The compiled graph to be executed.
inputs: The resources of inputs. Will be [=MLNamedArrayBufferViews/transfer|transferred=] if there are no validation errors.
outputs: The pre-allocated resources of required outputs. Will be [=MLNamedArrayBufferViews/transfer|transferred=] if there are no validation errors.
</pre>
which renders as:
Note that for all of these the return value of the method is not handled.