Re: [whatwg/streams] Add more cross-links (#872)

domenic requested changes on this pull request.

Sorry for the delay. A few minor nits, and suggestion for a larger fix that I (or you) can work on as a follow-up.

> @@ -105,9 +105,9 @@ 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. For
-web developer–created streams, the implementation details of a source are provided by an object with certain methods and
-properties that is passed to the {{ReadableStream()}} constructor.
+Readable streams are designed to wrap both types of sources behind a single, unified interface. For web
+developer–created streams, the <a href="#rs-constructor">implementation details of a source</a> are provided by an

Still not sure this helps that much compared to just clicking on the already-existing "ReadableStream() constructor" link, but I'm OK keeping it if you think so.

> @@ -385,15 +385,15 @@ like
 
 <pre><code class="lang-javascript">
   class ReadableStream {
-    constructor(underlyingSource = {}, { size, highWaterMark } = {})
+    <a href="#rs-constructor">constructor</a>(<a href="#rs-constructor">underlyingSource</a> = {}, { size, highWaterMark } = {})

Again the second link to the exact same place feels pretty redundant.

Maybe what this is pointing toward is the need for a dedicated section describing the underlying source objects, instead of putting it into the constructor's intro note? I guess same for the strategies too? I'd be happy to work on that as a follow-up. In the meantime I'm indifferent as to whether we include these redundant links or not.

> @@ -2778,12 +2778,13 @@ like
 
 <pre><code class="lang-javascript">
   class WritableStream {
-    constructor(underlyingSink = {}, { size, highWaterMark = 1 } = {})
+    <a href="#ws-constructor">constructor</a>(<a href="#ws-constructor">underlyingSink</a> = {}, { size, highWaterMark =
+    1 } = {})

I forgot that line wrapping is not a good idea inside `<pre>` blocks; sorry, we should undo this.

> @@ -4028,15 +4030,18 @@ readableStrategy)">new TransformStream(<var>transformer</var> = {}, <var>writabl
 
   <ul>
     <li><p><code>start(controller)</code> is called immediately, and is typically used to enqueue prefix <a>chunks</a>
-      that will be read from the <a>readable side</a> but don't depend on any writes to the <a>writable side</a>. If
-      this process is asynchronous, it can return a promise to signal success or failure.
+      using
+      {{TransformStreamDefaultController|controller}}.{{TransformStreamDefaultController/enqueue(chunk)|enqueue()}}.

I'd rather not have separate links for the controller since that's just a variable name, and it is described below. So just changing the linking text from enqueue() to controller.enqueue() is probably best here.

-- 
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/872#pullrequestreview-93007809