search

whatwg / streams

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

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

Open morlovich opened 1 month ago

morlovich commented 1 month 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 1 month ago

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

morlovich commented 1 month ago

Using it

ricea commented 1 month 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 1 month 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 1 month 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.