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

Minor typos, clarity tweaks, and suggestions #13

Open
13 of 14 tasks
domenic opened this issue Aug 13, 2014 · 1 comment
Open
13 of 14 tasks

Minor typos, clarity tweaks, and suggestions #13

domenic opened this issue Aug 13, 2014 · 1 comment
Labels

Comments

@domenic
Copy link

domenic commented Aug 13, 2014

  • "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 what return and throw 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 its getUserFromDatabase, 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, asynchronous forEach 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) and for (quote of quotes) are missing vars.
  • "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 what new Clock(1000, 500) does (without looking at the accompanying clock implementation).
  • The paragraph starting "Consider lifting an operator to a..." has lots of leftover &lt;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.
@kriskowal
Copy link
Owner

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.

kriskowal added a commit that referenced this issue Aug 16, 2014
Fixes #2
Fixes #3
Addresses #13 mostly
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

2 participants