read all bytes usage/signature may be hard to understand

[morlovich]

What is the issue with the Streams Standard?

https://streams.spec.whatwg.org/#readablestreamdefaultreader-read-all-bytes --- I've found the definition starting from |failureSteps| to be basically impossible to follow; there are too many levels of nesting going on here for me to follow unambiguously. Perhaps an example would help.

[ricea]

Are you speaking from the point of view of using the algorithm, or implementing the algorithm?

[morlovich]

Using it

[ricea]

I was going to point to https://fetch.spec.whatwg.org/#body-fully-read as an example, but it's quite hard to understand itself. Probably we can come up with a simpler example.

[morlovich]

That's ultimately what I ended up basing things on after a colleague pointed out the cross-spec cross-reference site, and this was easy enough for me to understand; unfortunately all the other uses of the method are also apparently technically wrong since they just act like it returns a Promise.

What I think ultimately happened is that I didn't realize that, in the streams spec, the stuff that's after the colon in "... which is an algorithm accepting a JavaScript value: read-loop given reader ... " is, to use C++ terms, the definition and not part of declaration. Maybe this is just a convention I didn't notice before and ought to have known, but then I probably did a bit more things with specs than most people who might be reading it anyway.

[MattiasBuelens]

This algorithm is using the "single sentence" format, as specified here (see: "Very short algorithms...").

However, I agree that as soon as the types of those arguments become complex (e.g. another algorithm taking arguments of its own), this becomes difficult to parse.

How about we put the (single) step in a numbered list below the declaration?

To read all bytes from a ReadableStreamDefaultReader reader, given successSteps, which is an algorithm accepting a byte sequence, and failureSteps, which is an algorithm accepting a JavaScript value:

1. Read-loop given reader, a new byte sequence, successSteps, and failureSteps.