Minor typos, clarity tweaks, and suggestions
domenic opened this issue · comments
- "If a promise is the temporal analogue ..." in this paragraph, you bold stream, asynchronous iterator, and asynchronous generator; however these are in different conceptual categories. Stream, reader, and writer are in the same conceptual category.
- Nearby, it would help to move the sentence about arrays, promises, and streams being exemplars instead of fundamental concepts above the discussion of promises and streams.
- When introducing iterators, iterations, done, and value, it would be helpful to discuss return values vs. values in the sequence up front. (That is,
{ value: x, done: true }
vs.{ value: y, done: false }
.) The introduction to iterators does not mention return values, but eventually you get around to it in the section on generator functions. Perhaps that is where they belong? But if so the way in which generators hijack the iteration object to express not only sequence values but also return values is worth calling out. - Typo: "We advance, the state machine to the first" should omit comma
- Typo: "lazilly"
- In the example of a generator for arrays, you explain what
yield
does, but not whatreturn
andthrow
do. - The code example following "The
then
method internally creates a new deferred..." is confusing; it's very unclear what its relation to the immediately-previous code sampel, and itsgetUserFromDatabase
, are. - "we return promises and continue when a promise resolves" should be fulfills, not resolves
- The sentences "Asynchronous
forEach
would return a task. Since streams are unicast, it stands to reason..." would be better as "Since streams are unicast, asynchronousforEach
would return a task. It stands to reason..." - The sentence "This example will fetch quotes from the works..." confused me for a good ten seconds until I realized that "This" meant "The following" not "The preceding."
- In "this example,"
for (title of titles)
andfor (quote of quotes)
are missingvar
s. - "signal can have plural producers and consumers" should s/plural/multicast or similar; you use "plural" mostly to talk about sequences in opposition to singular values.
- The
Clock
examples should use named option arguments; I have no idea whatnew Clock(1000, 500)
does (without looking at the accompanying clock implementation). - The paragraph starting "Consider lifting an operator to a..." has lots of leftover
<
s instead of<
s and so on. This is starting to get deeper into the document, where you haven't proofread as closely, I imagine.
Thanks for the plural/multiple. That was a global search/replace error, when I decided to use the word plural instead of multiple.
Yeah, the latter part of the document is older prose, which needs more of my attention for both consistency (because my ideas evolved) and attention (because it is simply later).
I am not sure I should s/resolve/fulfill/ in the last remaining task. There is a notion of "continue" that captures all kinds of resolution, which I perhaps should clarify instead.
Otherwise, I concur will all of these ideas and have a push coming soon.