Re: [streams] Merge ReadableByteStream into ReadableStream (#418)

> In addition to the idea by Domenic, can we separate internal operations and ones can be used directly by clients of each class? Too much?

Hmm. My first impression is that it's a bit too much, but I'm not sure. If you want to draft a quick bullet-point version of what the TOC would look like with your idea, we could discuss further.

> Domenic, in the example at #418 (comment) you've put all the abstract operations in the same section but giving sub sections under it. Does this mean that you think we should use one section parallel to sections explaining each class?
>
> Can we choose to put each operation to the corresponding big section explaining the class the operation operates on?

What I meant there was that, similar to the current spec, we want a section underneath "3 ReadableStreams" for abstract operations. Call it "3.5 Readable Stream Abstract Operations". Within that there'd be subsections.

If you think the abstract operations divide up cleanly enough that they could be nested under the class sections (so, e.g., "3.2.5 Abstract Operations for `ReadableStream`", "3.3.5 Abstract Operations for `ReadableStreamController`", etc.) then maybe that would work. I am a bit skeptical though. It seems like a lot of them are kind of hard to decide which class they are associated with. The organization in my comment seems more likely to be useful for readers.

In general, I'm open to suggestions on proposed organization; the best way to do that is to make concrete proposals with full TOCs.

> id for headings

I think we should keep the abbreviations, and we should endeavor to preserve as many links as possible. Nice short and well-curated IDs makes sense to me, for a spec that is of manageable size like this one.

I could imagine moving the abstract ops to a different ID style, like `#ao-IsReadableStream`. But that would break existing incoming links from e.g. Fetch, and I am not sure it is worth it.

> operation naming

I agree that it is probably a good idea to rearrange them with prefixes like you suggest.

> Any preference on the ordering of operations implementing the logic of class methods excluding the brand checking?

I think it's OK for them to not correspond perfectly. Let's keep it lexicographic.

---
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/streams/pull/418#issuecomment-190276398