CDDL definitions are not exported, but I get a warning about them

[domenic]

Repro steps: clone https://github.com/WICG/nav-speculation/blob/49f77f382eb709289b4baf1b66d22bd73e4c3eae/prefetch.bs and run bikeshed spec prefetch.bs.

I get various warnings like

LINT: Unexported dfn that's not referenced locally - did you mean to export it?
<dfn data-lt='method|"method"' data-dfn-type="cddl-key" data-dfn-for="speculation.PrefetchStatusUpdated" id="cddl-key-speculationprefetchstatusupdated-method" data-noexport="by-default" class="dfn-paneled"><code class="highlight"><c- s=""><c- nc="">method</c-></c-></code></dfn>

These come from the source code

<pre highlight="cddl" class="cddl" data-cddl-module="local-cddl">
SpeculationEvent = (
  speculation.PrefetchStatusUpdated
)
</pre>

I tried inserting an export attribute on the <pre> but that didn't seem to help.

I feel like either:

• CDDL definitions should be exported by default, like the IDL auto-generated definitions. (Might also help with Export browsingContext.BrowsingContext? w3c/webdriver-bidi#994.)
• This warning should not come up for CDDL definitions.

[tidoust]

CDDL definitions are not exported by default because they are not part of a single namespace. Various specs could define CDDL types such as error, message, event, etc. to mean different things. Exporting terms by default could potentially create duplicates. Now, that may only be a theoretical concern: current web specs tend to prefix type names (as done here) so there may not be any clash for now, and we could perhaps work with spec editors to consider their CDDL definitions as being part of a global namespace (and have custom logic for any residual duplicates).

That the warning does not show up for IDL terms as a consequence of them being exported is a sort of a bug to me: a spec that defines IDL terms in a <pre> block should have text that explains what it is for. Doesn't that apply to CDDL terms as well? Granted, there may not be much to say about the "speculation.prefetchStatusUpdated" value of the method key of the speculation.PrefetchStatusUpdated type.

[tabatkins]

An exported definition doesn't necessarily need to be referenced again in the defining spec; as you say, things like method arguments don't necessarily need to be talked about. So Bikeshed doesn't complain about that when they're exported. But if they're not exported and not referenced internally, that suggests that you probably intended it to be exported.

I agree that it's probably worthwhile to consider CDDL code in Web specs as part of the global web namespace, same as IDL and everything else. If it would really be annoying for common working modes (like error constructions), we can make it optional and turn it on by default in WHATWG and W3C, perhaps.

[tabatkins]

I tried inserting an export attribute on the <pre> but that didn't seem to help.

This sounds like a bug, tho. I'll investigate.

[domenic]

This remains pretty tricky because the spew of lint warnings hides other useful Bikeshed output in the prefetch spec. It's not blocking anything, but a fix would be much appreciated.

An exported definition doesn't necessarily need to be referenced again in the defining spec; as you say, things like method arguments don't necessarily need to be talked about. So Bikeshed doesn't complain about that when they're exported. But if they're not exported and not referenced internally, that suggests that you probably intended it to be exported.

I'm a little confused by this paragraph, as I often implicitly define method arguments and then never reference them explicitly.

For example, https://wicg.github.io/sanitizer-api/#dom-sanitizer-allowelement-element-element is a method argument that is never referenced explicitly. But building the spec doesn't generate a warning about that.

Could we treat CDDL definitions like we treat IDL method arguments (or other IDL constructs), and not warn about them? I think this is a sensible thing to do whether or not we go with the global namespace approach. (Which I also support.)

That the warning does not show up for IDL terms as a consequence of them being exported is a sort of a bug to me: a spec that defines IDL terms in a <pre> block should have text that explains what it is for. Doesn't that apply to CDDL terms as well? Granted, there may not be much to say about the "speculation.prefetchStatusUpdated" value of the method key of the speculation.PrefetchStatusUpdated type.

I don't really agree with this point of view. A lot of things in both IDL and CDDL are better "defined" by their usage, e.g. IDL/CDDL enum values, IDL interface names, IDL argument names, IDL/CDDL dictionary members.

You could have a bunch of English explanations as <dfn>s, separate from the IDDL/CDDL blocks, but they feel like busywork. Like, are people really helped by boilerplate sentences such as The <dfn>HTMLHtmlElement</dfn> interface is the interface for the <{html}> element? And there's the usual problem where these sorts of non-normative sentences can easily get out of sync with the normative impact on the processing model. (This is why our domintro blocks have prominent "For web developers (non-normative)" markers, because otherwise it's too easy to misunderstand them as normative definitions that are often less complete than or out of sync with the normative spec.)

[tidoust]

For example, https://wicg.github.io/sanitizer-api/#dom-sanitizer-allowelement-element-element is a method argument that is never referenced explicitly. But building the spec doesn't generate a warning about that.

The definitions in that spec seem strange to me though. That is, in "The allowElement(element) method steps are to allow an element with element and this’s configuration", I would expect "allowElement(element)" to be a reference to the IDL dfn in the IDL block (or the other way round), instead of exporting an "allowElement" term that can be referenced through [=allowElement=]. What's the reasoning behind exporting a generic term?

The element could be a reference to the definition in the IDL block as well in practice instead of being a var, although I agree that may be overkill (and makes editing more of a pain).

Could we treat CDDL definitions like we treat IDL method arguments (or other IDL constructs), and not warn about them? I think this is a sensible thing to do whether or not we go with the global namespace approach. (Which I also support.)

Not warning seems fine. Regarding the global namespace, I'm still wondering whether that is the right approach. Another example is the CDDL defined in the Open Screen Application spec that currently defines generic types such as status, request, response, microseconds. The spec could be updated, but then there should be no need to: the spec is more readable with shorter type names, and that CDDL module is not meant to be mixed with other CDDL modules defined elsewhere. If another organization that defines CDDL, say IETF, adopts Bikeshed for spec edition, we would also need to align on names.

I don't really agree with this point of view. A lot of things in both IDL and CDDL are better "defined" by their usage, e.g. IDL/CDDL enum values, IDL interface names, IDL argument names, IDL/CDDL dictionary members.

Definition by usage seems good to me and creates a reference that silences the warning. I don't disagree that IDL argument names probably go too far (although algorithms are very likely going to use them in practice). Things such as EventInit dictionary members would ideally not be needed at all. Anyway, no warning for lack of usage seems good enough, resulting specs can be analyzed later on to spot potential problems.

[domenic]

The definitions in that spec seem strange to me though.

That's fair, I was just trying to pick a random spec. It's not relevant to my larger point. Here's a more normal spec, with an example of the same non-referenced method argument: https://w3c.github.io/ServiceWorker/#dom-serviceworker-postmessage-message-transfer-message