Consider adding internal slots to taxonomy

[dontcallmedom]

See ongoing discussions in https://github.com/w3c/respec/issues/3644 - it may be that attribute and method are sufficient, but then maybe they shouldn't be exported by default?

[marcoscaceres]

I'd be ok with: defaults to "attribute", but can be a "method", and not exported by default.

[tidoust]

I'm not sure I understand the "not exported by default" proposal. Does it mean that:

1. ReSpec/Bikeshed would add a data-noexport attribute to these definitions?
2. Or does it mean that tools that extract definitions from the specs would need to understand that terms such as [[foo]]] are internal slots and have specific export rules?

In other words, would the change be internal to authoring tools? Or would the change affect the definitions contract?

I'm fine with 1 although I continue to think that it would be easier to introduce dedicated types for internal slots and methods (but then introducing new types may be more complex than meets the eye?). I'd prefer to avoid 2. as I think the goal of the contract is to keep things straightforward, and having to parse a term to understand whether it is exported or not seems wrong.

[dontcallmedom]

I definitely meant (1); I too have a preference for a dedicated type to avoid overloading the meaning of "attribute" and "method", but I could live with the other approach if introducing new types is found too costly for some reason.

(one cost could be the transition of the existing definitions, but arguably the authoring tools could detect the situation and automatically fix it with warnings)

[dontcallmedom]

another reason for a dedicate type: there are clear rules regarding acceptable values and case-sensitivity for attributes and methods, there are no such rules (that I know of) with regard to internal slots.

[marcoscaceres]

@tidoust wrote:

I'm not sure I understand the "not exported by default" proposal.

I.e., I mean the tool MUST NOT add data-export="". It must leave it to the spec editor to make that choice.

1. ReSpec/Bikeshed would add a data-noexport attribute to these definitions?

I was thinking tools "do nothing": i.e., leaving it to the spec editor to explicitly add data-exported="" if they want. However, tools would could (automatically) assign and verify a data-dfn-type of "attribute" or "method".

2. Or does it mean that tools that extract definitions from the specs would need to understand that terms such as [[foo]]] are internal slots and have specific export rules?

No. Extraction tools shouldn't need to do anything here.

@dontcallmedom wrote:

another reason for a dedicate type: there are clear rules regarding acceptable values and case-sensitivity for attributes and methods, there are no such rules (that I know of) with regard to internal slots.

This is true. Almost anything seems to go with internal slots... we have [[foo_bar]] and [[foo bar baz]] and [[foo bar]](args, barg, zarg) ... need to check. This is the current RegExp (which already gives you some idea of what we are dealing with:

/\[\[(\w+(?: +\w+)*)\]\](\([^)]*\)(\.[^)]*\))?)*$/; 

Fun example:

{{PublicKeyCredential/[[CollectFromCredentialStore]](origin, options, sameOriginWithAncestors)}}

More examples, just type [[ https://respec.org/xref/

[tidoust]

I'm not sure I understand the "not exported by default" proposal.

I.e., I mean the tool MUST NOT add data-export="". It must leave it to the spec editor to make that choice.

Then I'm still lost :) Let me try to reformulate.

The current rule is: "Either data-export or data-noexport MAY be provided (both boolean attributes). If neither is provided, dfn type definitions default to noexport, while all others default to export"
https://tabatkins.github.io/bikeshed/#dfn-contract

With the current rule, definitions with type attribute and method are exported by default, just like any dfn that does not have the type dfn. And so, internal slots are exported by default if they get defined with an attribute or method type, unless the spec editor adds a data-noexport attribute.

If you want "not exported by default", the rule needs to change somehow.

The rule may be changed for all attribute and method definitions, but that is likely going to affect a number of existing specs and xrefs! Is that what you have in mind?

The rule may also be changed for attribute and method definitions of internal slots, but then we'd be in option 2 above: "tools that extract definitions from the specs would need to understand that terms such as [[foo]] are internal slots". I believe we should avoid that.

Or the rule does not change, but then to keep internal slots private by default, authoring tools would need to add a data-noexport attribute to internal slots definitions, unless the spec editor explicitly adds a data-export attribute.

[marcoscaceres]

The current rule is: "Either data-export or data-noexport MAY be provided (both boolean attributes). If neither is provided, dfn type definitions default to noexport, while all others default to export"

Ah, ok. ReSpec doesn't add "noexport" itself, because we assume everything that is not WebIDL is private by default: We leave it for the spec editor to add "data-noexport" explicitly, but only to signal to other spec editors that this is private by design.

With the current rule, definitions with type attribute and method are exported by default, just like any dfn that does not have the type dfn. And so, internal slots are exported by default if they get defined with an attribute or method type, unless the spec editor adds a data-noexport attribute.

Right. That's not how ReSpec works (exports not added). Currently working on this patch:
https://github.com/w3c/respec/pull/3646

The rule may be changed for all attribute and method definitions, but that is likely going to affect a number of existing specs and xrefs! Is that what you have in mind?

I was thinking only for internal slots. Regular methods and attributes would be exported by default.

The rule may also be changed for attribute and method definitions of internal slots, but then we'd be in option 2 above: "tools that extract definitions from the specs would need to understand that terms such as [[foo]] are internal slots". I believe we should avoid that.

I agree. We should avoid that.

Or the rule does not change, but then to keep internal slots private by default, authoring tools would need to add a data-noexport attribute to internal slots definitions, unless the spec editor explicitly adds a data-export attribute.

I'd be ok with adding what you suggest above (explicit no-export if export is missing) to: https://github.com/w3c/respec/pull/3646

[dontcallmedom]

another potential reason for a dedicated type: not all internal slots can be linked to an IDL name; e.g. there are internal slots for the "relevant global object" (Audio Output Devices), or applied to un-IDL-named union of interfaces (track in Media Capture from DOM Elements).

("potential" as maybe this shouldn't be done that way?)

The ̀[[Name]]` notation comes from the EcmaScript Record field names convention, so presumably that type could be re-used to mark up definitions there.

[tabatkins]

I started the convention of marking up internal slots as attributes and/or methods (but with a [[x]] wrapper) because in the vast majority of cases they are attributes or methods, just ones that aren't author-exposed.

another potential reason for a dedicated type: not all internal slots can be linked to an IDL name

Those are potentially fine; nothing actually requires the for value to point to an IDL thing. One still needs to provide some sort of for value, to distinguish it from other interfaces with a slot named "[[explicitlyGrantedAudioOutputDevices]]" (unlikely as that particular example may be), but the mere fact that it doesn't have a particular IDL object to point to doesn't mean it shouldn't point to anything.

(And for the not-explicitly-defined union of track interfaces, that should just be for all the relevant interfaces.)

[dontcallmedom]

I don't dispute that internal slots may behave like attributes and methods in many sort of ways, but there are also many ways they don't (naming conventions, explicit typing, systematic association to an IDL interface to name a few), and keeping them into a single type feels wrong.

While it's fine to use the same micro-syntax for internal slots as for methods/attributes when authoring specs, I think losing the distinction in the type system pushes a lot of the potential adaption to these differences to data consumers.

i.e. instead of

switch(dfn.type) {
  case "attribute":
     // guaranteed there is no space or hypen in the name
     // well-defined IDL type 
     // dfn-for points to an interface
     // guaranteed this is not a sequence<>
  case "internalslot":
   // the sky is the limit
}

you end up with

switch(dfn.type) {
  case "attribute":
     if (name.startsWith("[[")) {
       // the sky is the limit
    } else {
      // guaranteed there is no space or hypen in the name
     // well-defined IDL type 
     // dfn-for points to an interface
     // guaranteed this is not a sequence<>
    }
}

[tabatkins]

I mean, that seems fine? Consumers of the raw data are, like, a half-dozen people max. And you've just correctly provided the way to distinguish between them. I'm not sure what additional benefit I'd receive in Bikeshed from being able to use one test vs the other.

Versus if we push the distinction into the type system, then every spec author needs to know about the distinction and correctly categorize their stuff.

It seems like a pretty strong priority-of-constituencies argument to categorize them as attributes/methods, then.

[dontcallmedom]

I hadn't considered the cost on spec authors (I was looking at this under the ReSpec perspective which sets that type automatically); I agree this is an important consideration, and that it would need a more convincing case than the one I've brought so far.