Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add more cross-links #872

Merged
merged 4 commits into from
Jan 31, 2018
Merged
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 35 additions & 28 deletions index.bs
Original file line number Diff line number Diff line change
Expand 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It mostly because of the point below, that as a reader it’s not obvious that the underlying source is defined at the constructor. I’d prefer leaving this link for now until we give underlyingSource its own section.

object with certain methods and properties that is passed to the {{ReadableStream()}} constructor.

<a>Chunks</a> are enqueued into the stream by the stream's <a>underlying source</a>. They can then be read one at a
time via the stream's public interface, in particular by using a <a>readable stream reader</a> acquired using the
Expand Down Expand Up @@ -141,8 +141,8 @@ Analogously to readable streams, most writable streams wrap a lower-level I/O si
queuing subsequent writes and only delivering them to the underlying sink one by one.

<a>Chunks</a> are written to the stream via its public interface, and are passed one at a time to the stream's
<a>underlying sink</a>. For web developer-created streams, the implementation details of the sink are provided by an
object with certain methods that is passed to the {{WritableStream()}} constructor.
<a>underlying sink</a>. For web developer-created streams, the <a href="#ws-constructor">implementation details of the
sink</a> are provided by an object with certain methods that is passed to the {{WritableStream()}} constructor.

Code that writes into a writable stream using its public interface is known as a <dfn>producer</dfn>.

Expand Down Expand Up @@ -385,15 +385,16 @@ like

<pre><code class="lang-javascript">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The introduction of links into these blocks is a great improvement; thank you!

class ReadableStream {
constructor(underlyingSource = {}, { size, highWaterMark } = {})
<a href="#rs-constructor">constructor</a>(<a href="#rs-constructor">underlyingSource</a> = {}, { size, highWaterMark
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I realize linking underlyingSource to ReadableStream() could be seen as questionable. This is just as suggestion. My thinking was that if someone’s looking at the class definition and the constructor, they are most likely a web developer and looking for an interface description. There’s multiple links to underlyingSource in the note, so there’s still a path to the definition.

} = {})

get locked()
get <a href="#rs-locked">locked</a>()

cancel(reason)
getReader()
pipeThrough({ writable, readable }, options)
pipeTo(dest, { preventClose, preventAbort, preventCancel } = {})
tee()
<a href="#rs-cancel">cancel</a>(reason)
<a href="#rs-get-reader">getReader</a>()
<a href="#rs-pipe-through">pipeThrough</a>({ writable, readable }, options)
<a href="#rs-pipe-to">pipeTo</a>(dest, { preventClose, preventAbort, preventCancel } = {})
<a href="#rs-tee">tee</a>()
}
</code></pre>

Expand Down Expand Up @@ -422,7 +423,7 @@ Instances of {{ReadableStream}} are created with the internal slots described in
<tr>
<td>\[[reader]]
<td class="non-normative">A {{ReadableStreamDefaultReader}} or {{ReadableStreamBYOBReader}} instance, if the stream
is <a>locked to a reader</a>, or <emu-val>undefined</emu-val> if it is not
is <a>locked to a reader</a>, or <emu-val>undefined</emu-val> if it is not
</tr>
<tr>
<td>\[[state]]
Expand Down Expand Up @@ -2778,12 +2779,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 } = {})
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


get locked()
get <a href="#ws-locked">locked</a>()

abort(reason)
getWriter()
<a href="#ws-abort">abort</a>(reason)
<a href="#ws-get-writer">getWriter</a>()
}
</code></pre>

Expand Down Expand Up @@ -3974,10 +3976,11 @@ like

<pre><code class="lang-javascript">
class TransformStream {
constructor(transformer = {}, writableStrategy = {}, readableStrategy = {})
<a href="#ts-constructor">constructor</a>(<a href="#ts-constructor">transformer</a> = {}, <a
href="#ws-constructor">writableStrategy</a> = {}, <a href="#rs-constructor">readableStrategy</a> = {})

get readable()
get writable()
get <a href="#ts-readable">readable</a>()
get <a href="#ts-writable">writable</a>()
}
</code></pre>

Expand Down Expand Up @@ -4028,15 +4031,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()}}.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Those chunks 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.

<li>
<p><code>transform(chunk, controller)</code> is called when a new chunk originally written to the writable side is
ready to be transformed. It can return a promise to signal success or failure of the transformation. The results
of the transformation can be enqueued to the readable side using the
{{ReadableStreamDefaultController/enqueue(chunk)|controller.enqueue()}} method. This permits a single chunk
written to the writable side to result in zero or multiple chunks on the readable side.
{{TransformStreamDefaultController|controller}}.{{TransformStreamDefaultController/enqueue(chunk)|enqueue()}}
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you think about splitting the links to contain both the class definition as well as the method definition?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Additionally, was it intentional that this linked to ReadableStreamDefaultController.enqueue() instead of TransformStreamDefaultController.enqueue()

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm 99% sure that linking to ReadableStreamDefaultController.enqueue() was a mistake here. Thanks for catching it.

Splitting the links looks okay to me, but I will defer to @domenic who knows much more about correct markup fro WhatWG standards.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also change this one?

method. This permits a single chunk written to the writable side to result in zero or multiple chunks on the
readable side.

<p>The stream implementation guarantees that <code>transform</code> will be called only after previous
transformations have succeeded, and never before <code>start</code> has completed or after <code>flush</code> is
Expand All @@ -4053,10 +4059,11 @@ readableStrategy)">new TransformStream(<var>transformer</var> = {}, <var>writabl
instance of {{TransformStreamDefaultController}}, and has the ability to enqueue chunks to the readable side,
or to terminate or error the stream.

The second and third arguments to the constructor are the <a>queuing strategy</a> objects for the writable and
readable sides respectively. These are used in the construction of the {{WritableStream}} and {{ReadableStream}}
objects and can be used to add buffering to a {{TransformStream}}, in order to smooth out variations in the speed of
the transformation, or to increase the amount of buffering in a <a>pipe</a>.
The second and third arguments to the constructor, <code>writeableStrategy</code> and <code>readableStrategy</code>,
are the <a>queuing strategy</a> objects for the writable and readable sides respectively. These are used in the
construction of the {{WritableStream}} and {{ReadableStream}} objects and can be used to add buffering to a
{{TransformStream}}, in order to smooth out variations in the speed of the transformation, or to increase the amount
of buffering in a <a>pipe</a>.
</div>

<emu-alg>
Expand Down