Re: [whatwg/streams] Revise abstract, introduction, and model (#779)

ricea approved this pull request.

lgtm

> @@ -68,32 +64,40 @@ urlPrefix: https://tc39.github.io/ecma262/; spec: ECMASCRIPT
 
 <em>This section is non-normative.</em>
 
+<div class="non-normative">

This is the only use of this class in the spec. Should we have a separate issue to add more?

> @@ -118,49 +122,64 @@ constantly being pushed from the OS level, at a rate that can be controlled by c
 synchronously, e.g. if it is held by the operating system's in-memory buffers, or asynchronously, e.g. if it has to be
 read from disk. An example pull source is a file handle, where you seek to specific locations and read specific amounts.
 
-Readable streams are designed to wrap both types of sources behind a single, unified interface.
+Readable streams are designed to wrap both types of sources behind a single, unified interface. The implementation
+details of a source are provided by an object containing certain methods and properties that is passed to the

"containing" may have a specific meaning here. If not I would prefer "having".

The mixture of plural and singular forms in this sentence requires the reader to backtrack to parse it. I'm not sure what the best fix would be, but maybe split it? For example,

> A source is implemented as an object having specific methods and properties. It is passed to the {{ReadableStream()}} constructor.

>  
-Consumers can also <dfn lt="tee a readable stream">tee</dfn> a readable stream. This will
-<a lt="locked to a reader">lock</a> the stream, making it no longer directly usable; however, it will create two new
-streams, called <dfn lt="branches of a readable stream tee">branches</dfn>, which can be consumed independently.
+Consumers can also <dfn lt="tee a readable stream">tee</dfn> a readable stream using its {{ReadableStream/tee()}}
+method. This will <a lt="locked to a reader">lock</a> the stream, making it no longer directly usable; however, it will
+create two new streams, called <dfn lt="branches of a readable stream tee">branches</dfn>, which can be consumed
+independently.
 
 For streams representing bytes, an extended version of the <a>readable stream</a> is provided to handle bytes
 efficiently, in particular by minimizing copies. The <a>underlying source</a> for such a readable stream is called
 a <dfn>underlying byte source</dfn>. A readable stream whose underlying source is an underlying byte source is sometimes

Should "a underlying byte source" be "an underlying byte source"?

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/streams/pull/779#pullrequestreview-58924468