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.

Sign up for GitHub

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

Add more cross-links #872

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
826fe9f
Add more cross-links
surma Jan 26, 2018
c5c106a
Move some of the links into descriptive text
surma Jan 27, 2018
afe4805
Can't wrap code blocks
surma Jan 27, 2018
322ad72
Review by @domenic
surma Jan 31, 2018
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
46 changes: 23 additions & 23 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ A <dfn export>readable stream</dfn> represents a source of data, from which you
<em>out</em> of a readable stream. Concretely, a readable stream is an instance of the {{ReadableStream}} class.

Although a readable stream can be created with arbitrary behavior, most readable streams wrap a lower-level I/O source,
called the <dfn>underlying source</dfn>. There are two types of underlying source: push sources and pull sources.
called the <dfn>underlying source</dfn> ([[#rs-constructor|interface description]]). There are two types of underlying source: push sources and pull sources.
Copy link
Member

Choose a reason for hiding this comment

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

This isn't good, because we're currently talking about the general concept of underlying sources, not the JS objects that sometimes (for web-developer-created streams) embody them. Such a link belongs later, where we say "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." But, that already links to the constructor, so I'm not sure if there's anything to do here.

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 see your point. The problem that I’m trying to solve here is the following flow:

  1. Go to stream spec
  2. Click “ReadableStream” in ToC
  3. Get confused, maybe click ReadableStream again?
  4. Okay, I’m at the class, I see underlyingSource, but I can’t click it. The paragraph has a clickable “underlying Source”, tho. So let’s click that.
  5. I was already here...

Maybe we can turn underlyingSource in the class definition into a link to the note? Would that be acceptable?


<dfn lt="push source">Push sources</dfn> push data at you, whether or not you are listening for it. They may also
provide a mechanism for pausing and resuming the flow of data. An example push source is a TCP socket, where data is
Expand Down Expand Up @@ -137,7 +137,7 @@ A <dfn export>writable stream</dfn> represents a destination for data, into whic
goes <em>in</em> to a writable stream. Concretely, a writable stream is an instance of the {{WritableStream}} class.

Analogously to readable streams, most writable streams wrap a lower-level I/O sink, called the
<dfn>underlying sink</dfn>. Writable streams work to abstract away some of the complexity of the underlying sink, by
<dfn>underlying sink</dfn> ([[#ws-constructor|interface description]]). Writable streams work to abstract away some of the complexity of the underlying sink, by
Copy link
Member

Choose a reason for hiding this comment

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

Same problem as above.

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
Expand Down Expand Up @@ -385,15 +385,15 @@ 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 } = {})
<l>[[#rs-constructor|constructor]]</l>(underlyingSource = {}, { size, highWaterMark } = {})
Copy link
Member

Choose a reason for hiding this comment

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

Personally I find this more confusing than just doing <a href="#rs-constructor">constructor</a>. Does that work, or is only <l> allowed inside <pre> blocks?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Just tested it. Works as well.


get locked()
get <l>[[#rs-locked|locked]]</l>()

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

Expand Down Expand Up @@ -444,11 +444,11 @@ ReadableStream(<var>underlyingSource</var> = {}, { <var>size</var>, <var>highWat
govern how the constructed stream instance behaves:

<ul>
<li><p><code>start(controller)</code> is called immediately, and is typically used to adapt a <a>push
<li><p><code>start({{ReadableStreamDefaultController|controller}})</code> is called immediately, and is typically used to adapt a <a>push
Copy link
Contributor Author

Choose a reason for hiding this comment

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

This one is a bit questionable because it could also be a BYOB, but I think having it clickable is worth the simplification.

Copy link
Member

Choose a reason for hiding this comment

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

I'm not really OK with linking variable names to their types in general, here or elsewhere. (Especially, as you say, when their types are not accurate.) If you think it's unclear what the type of the controller is, we should add a more explicit sentence explaining.

This occurs several times below; I'll avoid noting it each time.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

That’s fair. I’ll take a stab at rephrasing the text so I can add some links to that instead.

source</a> by setting up relevant event listeners, or to acquire access to a <a>pull source</a>. If this process
is asynchronous, it can return a promise to signal success or failure.

<li><p><code>pull(controller)</code> is called when the stream's <a>internal queue</a> of chunks is not full, and
<li><p><code>pull({{ReadableStreamDefaultController|controller}})</code> is called when the stream's <a>internal queue</a> of chunks is not full, and
will be called repeatedly until the queue reaches its <a>high water mark</a>. If <code>pull</code> returns a
promise, then <code>pull</code> will not be called again until that promise fulfills; if the promise rejects, the
stream will become errored.
Expand Down Expand Up @@ -2778,12 +2778,12 @@ like

<pre><code class="lang-javascript">
class WritableStream {
constructor(underlyingSink = {}, { size, highWaterMark = 1 } = {})
<l>[[#ws-constructor|constructor]]</l>(underlyingSink = {}, { size, highWaterMark = 1 } = {})

get locked()
get <l>[[#ws-locked|locked]]</l>()

abort(reason)
getWriter()
<l>[[#ws-abort|abort]]</l>(reason)
<l>[[#ws-get-writer|getWriter]]</l>()
}
</code></pre>

Expand Down Expand Up @@ -2866,11 +2866,11 @@ WritableStream(<var>underlyingSink</var> = {}, { <var>size</var>, <var>highWater
how the constructed stream instance behaves:

<ul>
<li><p><code>start(controller)</code> is called immediately, and can perform any actions necessary to acquire
<li><p><code>start({{WritableStreamDefaultController|controller}})</code> is called immediately, and can perform any actions necessary to acquire
access to the <a>underlying sink</a>. If this process is asynchronous, it can return a promise to signal success
or failure.

<li><p><code>write(chunk, controller)</code> is called when a new <a>chunk</a> of data is ready to be written to the
<li><p><code>write(chunk, {{WritableStreamDefaultController|controller}})</code> is called when a new <a>chunk</a> of data is ready to be written to the
<a>underlying sink</a>. It can return a promise to signal success or failure of the write operation. The stream
implementation guarantees that this method will be called only after previous writes have succeeded, and never
after <code>close</code> or <code>abort</code> is called.
Expand Down Expand Up @@ -3974,10 +3974,10 @@ like

<pre><code class="lang-javascript">
class TransformStream {
constructor(transformer = {}, writableStrategy = {}, readableStrategy = {})
<l>[[#ts-constructor|constructor]]</l>(transformer = {}, writableStrategy = {}, readableStrategy = {})

get readable()
get writable()
get <l>[[#ts-readable|readable]]</l>()
get <l>[[#ts-writable|writable]]</l>()
}
</code></pre>

Expand Down Expand Up @@ -4027,12 +4027,12 @@ readableStrategy)">new TransformStream(<var>transformer</var> = {}, <var>writabl
how the constructed stream instance behaves:

<ul>
<li><p><code>start(controller)</code> is called immediately, and is typically used to enqueue prefix <a>chunks</a>
<li><p><code>start({{TransformStreamDefaultController|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.

<li>
<p><code>transform(chunk, controller)</code> is called when a new chunk originally written to the writable side is
<p><code>transform(chunk, {{TransformStreamDefaultController|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
Expand All @@ -4043,7 +4043,7 @@ readableStrategy)">new TransformStream(<var>transformer</var> = {}, <var>writabl
called. When no <code>transform</code> method is supplied, the identity transform is used, which enqueues chunks
unchanged from the writable side to the readable side.

<li><p><code>flush(controller)</code> is called after all chunks written to the writable side have been
<li><p><code>flush({{TransformStreamDefaultController|controller}})</code> is called after all chunks written to the writable side have been
transformed and the writable side has been closed. It is typically used to enqueue suffix chunks to the
readable side, before that too becomes closed. If this process is asynchronous, it can return a promise
to signal success or failure.
Expand Down