Alternate argumentdef styling

[inexorabletash]

WebNN uses a style of defining method arguments that's similar to the style promoted for Free Type/Etc Documentation on Attributes/Dict Members - here's an example

I was investigating and discussing adopting more Bikeshed style and linking over in webmachinelearning/webnn#574 - the alternatives seem to be (1) keep something like the current style, and manually link with <div dfn-for="Foo/bar(baz)" dfn-type="argument"> ... <dfn>baz</dfn> ... - which is fragile - if you make a typo or the IDL changes you don't get any warnings, and you don't get free type/etc docs, or (2) adopt the <pre class="argumentdef"> approach which has excellent spec author ergonomics (nice errors, free type/etc docs) but has huge tables that squish the descriptions into a tiny column.

Is there any appetite for something in between, e.g. expanding "Free Type/Etc Documentation on Attributes/Dict Members" to cover method arguments (data-method-argument-info ?), or an alternate styling for argumentdef blocks that's more like the dl/dt/dd ?

[tabatkins]

Yeah, I'm open to having more than one rendering option here. We could stick with a table, but have the descriptions take up an entire second row underneath each entry, or render as a dl similar to what you're doing manually right now. Feel free to explore what markup you might want, and I'll see what I can do about it. (Not for a bit, tho - I'm busy this week and on vacation next week.)

[tabatkins]

Hmm, tho also, I already have support for doing this sort of auto-checking/filling with dls if you're referencing attributes (or dict members), like you can do:

<dl dfn-type=attribute dfn-for=Foo>
: <dfn>bar</dfn>
:: Description of Foo.bar
...
</dl>

and your dt will automatically get the type, whether it's readonly or nullable, and its default value.

I don't see why I couldn't extend this to method arguments, too.

[tabatkins]

Ah, you even reference that functionality already. Cool then, yeah, I could definitely extend this to function args.

[inexorabletash]

The WG preferred <UL> styling over <DL> and <TABLE>. So adding a function arg variant like data-attribute-info and data-dict-member-info would be the minimal change and let us control the presentation rather than having to bake it into Bikeshed.

But I should see if <span data-attribute-info for="FooInterface/fooAttr"></span> emits errors if there's no match, as that's an important part of maintainability...

[tabatkins]

If it doesn't I can fix that.

[inexorabletash]

For posterity: I can confirm that I do see the desired diagnostic errors using this style if there's a name mismatch.

interface FooInterface {
  readonly attribute DOMString? fooAttr;
};

dictionary BarDictionary {
  required DOMString? barMember;
};

And either

<dl dfn-type=attribute dfn-for=FooInterface>
  <dt><dfn>fooAttr</dfn>
  <dd>...
</dl>

<dl dfn-type=dict-member dfn-for=BarDictionary>
  <dt><dfn>barMember</dfn>
  <dd>...
</dl>

or

* <dfn attribute for=FooInterface>fooAttr</dfn> 
    <span data-attribute-info for="FooInterface/fooAttr"></span> ...
* <dfn dict-member for=BarDictionary>barMember</dfn>
    <span data-dict-member-info for="BarDictionary/barMember"></span> ...

(Feature creep: support putting data-info on the <dfn> itself to get the content appended, to avoid repetition.)