Respec: Link or unlink iterable<>?

[saschanaz]

Currently we don't prevent links for iterable<>, causing <dfn> for "iterable" does not exist warning.

https://github.com/w3c/respec/blob/c23d764aa7f6f31f7f87b916c6fa8ba858b7f0f6/src/core/dfn-finder.js#L14-L17

But I haven't seen any spec that has a spec definition for iterable. What should be done?

cc: @marcoscaceres

[marcoscaceres]

mmm... I guess try to link, and if not in-document definition, link to WebIDL spec?

[saschanaz]

try to link, and if no in-document definition, link to WebIDL spec?

Introducing a feature that nobody would use feels like a non-starter... especially given that Bikeshed does not link iterable to anywhere and people are still happy.

Also I'm not sure what should be done here:

[Exposed=Window]
interface Foo {
  attribute FrozenArray<DOMString> _iterable; // idl-foo-iterable
  iterable<DOMString>; // idl-foo-iterable?

  DOMString _stringifier(); // idl-foo-stringifier
  stringifier; // idl-foo-stringifier?
};

I think nobody will do this but still it's a possible name collision. Maybe it can use ! like idl-foo!iterable as overloads currently do?

[marcoscaceres]

especially given that Bikeshed does not link iterable to anywhere and people are still happy.

I don't know if we can make that determination about happiness. I would certainly appreciate being able tot click on "stringifier" to actually read how it's implemented (either in the spec, or default behavior in IDL).

attribute FrozenArray<DOMString> _iterable; // idl-foo-iterable

Agree. Links to attribute.

iterable<DOMString>; // idl-foo-iterable?

I think here we actually should link to Web IDL. Is there any reason for a spec to override the definition of "iterable"?

(same comments for stringifier)

[marcoscaceres]

stringifier; // idl-foo-stringifier?

If I remember correctly, this means .toString() must be implemented for stringifier - So searching for "foo.toString()" in the spec might make sense... and if it's not there, fall back to WebIDL.

I can't remember if iterable puts any requirements on the defining spec.

[saschanaz]

and if it's not there, fall back to WebIDL.

I don't like the suggested fallbacking behavior, as it would make me assume there be a special definition within the spec. Clicking that and instead being redirected to a Web IDL spec is IMO a user experience nightmare 😥

[marcoscaceres]

I might be misunderstanding. Is it different to how we currently link to the IDL spec for DOMString?

[saschanaz]

AFAIK it does not fallback and always go IDL so I can always expect the same behavior. Fallbacking shows a link that may be linked to the current page or the IDL spec for the same IDL member.

[marcoscaceres]

AFAIK it does not fallback and always go IDL so I can always expect the same behavior.

Agree. yes.

Fallbacking shows a link that may be linked to the current page or the IDL spec for the same IDL member.

Yes, you are right. But the question is if the spec author is allowed to override or specify custom behavior. If yes, then it must be possible to link to the overridden behavior. But if not, then exclusively linking directly to IDL makes perfect sense (like with DOMString).

Hopefully I got that right? ... To be clear, I'm only suggesting we allow override is we absolutely need to - and if we don't, then we just point to the IDL spec.

[marcoscaceres]

(I trust your judgement tho! Please do whatever you think is best!!!!)

[saschanaz]

I would agree with the spec author point of view, but somehow disagree with the reader PoV. My preferred way:

1. No link by default (as other syntaxs e.g. attribute, getter etc. do not).
2. Link when author wants (so that readers can easily know that the spec includes a definition for this, by the existence of the link).

[marcoscaceres]

The above sounds good. Let's go with it.

[saschanaz]

@marcoscaceres BTW do we have a list of specs that use ReSpec? I wonder what the actual specs do for iterable<> because the current setup will generate a warning if no corresponding dfn exists.

[marcoscaceres]

No list, unfortunately. But let's see I can do a quick search...

[marcoscaceres]

https://w3c.github.io/encrypted-media/#mediakeystatusmap-interface

[saschanaz]

Thanks! But that text... is just a duplication from Web IDL. Hmm.

[marcoscaceres]

Lol, I didn’t actually click it. I’ll see if I can another.