Flow docs #1432
Flow docs #1432
Conversation
This make the whole TOC to look more consistent.
There was a problem hiding this comment.
Tremendous work!
-
"Flow context" paragraph should expose the fact, that code withing
foo's flow is executed in the context of the caller, not thecollectoperator.
Code sample should includefoobody with a comment as well. -
"Wrong emission withContext" paragraph -- unformatted exception message.
-
"Exception transparency" paragraph.
The catch intermediate operator, honoring exception transparency, catches only exceptions in its upstream flows.
"in its upstream flows" is not the correct phrasing. For example, "catches exceptions from the upstream aka from all the operators above the catch operator, but not the below" (or using "preceding" and "antecedent" terms).
If the block in collect { ... } downstream of catch throws an exception
This one can probably be rephrased in a more understandable manner as well. "collect downstream of catch" may not fully expose the idea.
-
In general, "Flows" sounds unnatural, probably it's worth to replace phrases like "flows represent" with "flow represent".
-
It feels like the guide ends right in the middle of the story. It would be nice to have a paragraph about
launchIn(right after the declarative approach withcollect()) and more general paragraph emphasizing that flow can be used both in declarative and imperative ways (similarly to loops and sequence operators) and that we do not enforce one way over another.
* Added new example showing how flow body executed in the collector's context. * Better formatting for flowOn operator exceptions.
There was a problem hiding this comment.
Added a few sections, please take a look. Additionally, asked David to proofread the text.
In general, the structure looks good, though I still have a feeling (not really actionable at this point) that the second half is focused on the API instead of concepts
* Shorter example codes with less lines output.
* Added "Upstream exceptions only" section with additional example.
* "Imperative versus declarative" section moved one level up.
* Consistent empty lines and tense use ("will print" -> "prints", etc).
|
Reviewed and edited additional section about |
No description provided.