Separate out exported abstract ops from internal ones

[domenic]

Ideally, other specs should only refer to a few of our abstract ops, e.g.:

• AcquireReadableStreamReader ( stream )
• CloseReadableStream ( stream )
• EnqueueInReadableStream ( stream, chunk )
• ErrorReadableStream ( stream, e )
• IsReadableStream ( x )
• IsReadableStreamLocked ( stream )
• TeeReadableStream ( stream, shouldClone )

plus maybe a few more. Others are "implementation details", e.g. FinishClosingReadableStream ( stream ) or RequestReadableStreamPull ( stream ) or similar. Additionally, for each of the above, there are some "usage details" that are important. E.g. see the intro of https://streams.spec.whatwg.org/#enqueue-in-readable-stream

A few strategies:

• Separate sections, e.g. exported abstract ops and internal abstract ops
• Some kind of tag, like that proposed for Notate abstract ops that can throw #371
• A separate "for other specifications" section describing the usage of exported abstract ops
  • Pro: authors of other specs probably don't care to actually read the details of e.g. EnqueueInReadableStream
  • Con: duplication; keeping in sync; is this normative or non-normative?
• Some kind of toggle switch that gives you a "for other spec authors" view, which hides any non-exported abstract ops (and maybe hides the algorithms for the exported ones?)

Thoughts appreciated. Probably especially from @annevk as Fetch editor.

[annevk]

I think ideally you can find out from the name which is private and which is public. Would prefixing internal methods with "@" be too weird?

[domenic]

That seems pretty weird but maybe it will grow on me. You like it better than the tag idea?

[annevk]

A bit, the tags might not make it into other specifications.

[domenic]

Yeah, they wouldn't... but if everyone behaves themselves, neither would any @-prefixed internal methods :P

[annevk]

This has often confused me with ECMAScript too. And is a problem with most specifications today. A lot of algorithms and not clear which are reusable and which are not. Glad you're leading the way.

[tyoshino]

Any of separate section, tag, prefixing work for me. Regardless we put tag/prefix or not, grouping into two sections would improve readability, I guess.

[domenic]

One way of doing this is to move stuff like https://fetch.spec.whatwg.org/#streams into the spec. That way we achieve a few things at once:

• Let streams define how to manipulate streams, instead of letting Fetch do it
• Give people the ability to use English to invoke these operations, instead of function call syntax, since that seems to be important
• Make it clear what we expect other specs to invoke

[annevk]

I would be happy to use abstract operations in Fetch in due course. Though English might be a tad more readable at times.

[annevk]

What's the plan here now that Streams is using IDL?

[domenic]

Roughly the same, and much closer to the top of my to-do list. My current plan is:

• Survey Fetch, Service Workers, Native Filesystem, Serial API, etc. to find out what they need.
• Wrap everything up into English prose-style algorithms and indirections in a tentative PR. (Including removing export="" on abstract ops.)
• Send tentative PRs to those specs and get feedback. (Including, for Fetch, removing https://fetch.spec.whatwg.org/#streams.)
• Merge them all at once.