search

whatwg / streams

Streams Standard
https://streams.spec.whatwg.org/
Other
1.35k stars 161 forks source link

read all bytes usage/signature may be hard to understand #1315

Open morlovich opened 6 months ago

morlovich commented 6 months ago

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 commented 6 months ago

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

morlovich commented 6 months ago

Using it

ricea commented 6 months ago

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 commented 6 months ago

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 commented 6 months ago

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.