Respec: WebIDL & <dl> tag

[ktk]

There used to be a <dl> tag in ReSpec, this was used to create nicer looking API docs like for example in this example (side note: this link really confused me as it seems to show the date of today as revision so I first thought this is the latest version of the spec).

Did this get purged at one point? The WebIDL examples in the current spec look super minimal and it's in my opinion really hard to make that readable. I would have to introduce quite some formatting to mimic a comparable API documentation.

What are other projects doing in that regard?

[marcoscaceres]

So, as a community, we decided that WebIDL conveys the exact level of information (and the WebIDL tables are thus redundant, because they just replicate what the IDL says). Another issue was that the IDL tables made specs huge, making specs bloated.

What are other projects doing in that regard?

BikeShed/all WHATWG specs also uses the minimal style

[marcoscaceres]

Sorry, hit enter too soon... fixed above.

[ktk]

Thanks for the info, my question was more in terms of is there really no predefined CSS we can use to make API documentation (arguments, return values etc) look better? I find it quite hard to make that appealing that way.

[marcoscaceres]

Oh, got you. We can totally try to fix that. I’m open to suggestions.

[marcoscaceres]

Oh wait, you mean the wiki? That’s controlled by Github I think. But can check.

[ktk]

No I mean in ReSpec itself. I see that the old table-style was complex but I would appreciate to have tags where we can make API specs look better. Something in the direction of what JSDoc tooling generates, like:

That is from an example of documentation.js.

It does not have to be fancy, just a bit more than what is there now.

[marcoscaceres]

Ok, thanks for helping me understand. Part of what might help here will be landing soon:
https://github.com/w3c/respec/pull/1850

I think we should make method definitions automatically have their arguments added. Possibly also the return type. Then we don’t need a table, and all the bits are in place for styling. Then all the info is in the definition, as well as the right markup for styling.

Any chance you could experiment with some markup and style options?

[ktk]

Thanks @marcoscaceres, the linked issue is a step in the right direction. However, there are still things I miss:

• a description for the method itself. This section says what the code is or does.
• a description for each parameter of the method

In the linked issue you have a method with no arguments, how would it look like with arguments?

[marcoscaceres]

In the linked issue you have a method with no arguments, how would it look like with arguments?

I guess I would do:

<p>
  The <dfn>foo(<var data-type="Bar">arg1</var>, <var data-type="Baz">arg2</var>)</dfn> 
   method acts of follows: 
</p>
<ol class="algorithm">
   <li>If <var>arg1</var> ... </li>
</ol>

And so on... That describes the data type, and the behavior of those types is described in the algorithm. WebIDL handles the coercion.

Alternatively:

<p>
  The <dfn>foo(arg1, arg2)</dfn> method acts of follows. 
  It takes <var data-type="Bar">arg1</var>, 
  which is the bar you want to get to. And <var data-type="Baz">arg2</var>, 
  which is how much "baz" you need: 
</p>
<ol class="algorithm">
   <li>If <var>arg1</var> ... </li>
</ol>

[marcoscaceres]

closing as answered.