2.x: Expand the Getting Started #5926

akarnokd · 2018-03-22T14:06:37Z

This PR expands the Readme.md with further examples and details, plus adds headers so that (former and new) sections can be easily linked in answers on issue lists or StackOverflow.

(Note that it was written offline without proper markdown rendering so I may update the PR a couple of times to get the render mistakes fixed).

codecov · 2018-03-22T14:22:24Z

Codecov Report

Merging #5926 into 2.x will increase coverage by 0.01%.
The diff coverage is n/a.

@@             Coverage Diff              @@
##                2.x    #5926      +/-   ##
============================================
+ Coverage     98.24%   98.25%   +0.01%     
+ Complexity     6021     6017       -4     
============================================
  Files           656      656              
  Lines         44040    44040              
  Branches       6102     6102              
============================================
+ Hits          43265    43272       +7     
+ Misses          235      226       -9     
- Partials        540      542       +2

Impacted Files	Coverage Δ	Complexity Δ
.../operators/flowable/FlowableBlockingSubscribe.java	`91.89% <0%> (-5.41%)`	`9% <0%> (-1%)`
...tivex/internal/observers/FutureSingleObserver.java	`94.33% <0%> (-3.78%)`	`24% <0%> (-1%)`
.../io/reactivex/internal/schedulers/IoScheduler.java	`89.24% <0%> (-3.23%)`	`9% <0%> (ø)`
...tivex/internal/schedulers/TrampolineScheduler.java	`96.1% <0%> (-2.6%)`	`6% <0%> (ø)`
...ators/flowable/FlowableWindowBoundarySupplier.java	`96.22% <0%> (-2.52%)`	`2% <0%> (ø)`
...ternal/operators/completable/CompletableMerge.java	`96.42% <0%> (-2.39%)`	`2% <0%> (ø)`
...activex/internal/schedulers/ScheduledRunnable.java	`98.07% <0%> (-1.93%)`	`29% <0%> (-1%)`
.../operators/mixed/FlowableConcatMapCompletable.java	`98.29% <0%> (-1.71%)`	`2% <0%> (ø)`
...rnal/subscriptions/DeferredScalarSubscription.java	`98.46% <0%> (-1.54%)`	`28% <0%> (-1%)`
...ernal/operators/flowable/FlowableFlatMapMaybe.java	`91.78% <0%> (-1.45%)`	`2% <0%> (ø)`
... and 24 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f363ef0...d233b66. Read the comment docs.

akarnokd · 2018-03-22T14:43:30Z

Haven't encountered any rendering problems.

vanniktech · 2018-03-22T14:57:26Z

README.md

+The dataflows in RxJava consist of a source, zero or more intermediate steps followed by a data consumer or combinator step (where the step is responsible to consume the dataflow by some means):
+
+```java
+


are those new lines necessary?

Those seem to be stripped from the final render:

In this case though, there was a line there which got accidentally deleted.

artem-zinnatullin · 2018-03-22T15:09:08Z

README.md

 The first step is to include RxJava 2 into your project, for example, as a Gradle compile dependency:

 ```groovy
 compile "io.reactivex.rxjava2:rxjava:2.x.y"
 ```

+(Please replace `x` and `y` with the latest version numbers: [![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.reactivex.rxjava2/rxjava/badge.svg)](https://maven-badges.herokuapp.com/maven-central/io.reactivex.rxjava2/rxjava)


Badge image is not displaying, I think [ before ! is not needed

https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#images

Ah, you want to make it clickable, then something wrong with syntax or my browser (Firefox 59.0.1)

It is the same markdown as in the beginning of the readme file where the top badges are located. Sometimes the maven badge simply fails to load. I'm assuming this is due to throttling at the host service where maven-badges lives.

artem-zinnatullin

Great rewrite!

Sorry can't finish it right now (don't want to block merge though), posting partial review

artem-zinnatullin · 2018-03-22T15:12:53Z

README.md

+  - [`io.reactivex.Completable`](http://reactivex.io/RxJava/2.x/javadoc/io/reactivex/Completable.html): a flow without items but only a completion or error signal,
+  - [`io.reactivex.Maybe`](http://reactivex.io/RxJava/2.x/javadoc/io/reactivex/Maybe.html): a flow with no items, exactly one item or an error.
+
+### Some terminology


nit: "Some" → "Common"?

These are not all the terminology but those which appear later in the text and I felt I have to define them upfront.

artem-zinnatullin · 2018-03-22T15:16:03Z

README.md

+
+#### Upstream, downstream
+
+The dataflows in RxJava consist of a source, zero or more intermediate steps followed by a data consumer or combinator step (where the step is responsible to consume the dataflow by some means):


"combinator" → "operator"?

I see few other usages of "combinator" https://github.com/ReactiveX/RxJava/search?q=combinator&type=Code&utf8=%E2%9C%93 but idk, doesn't look like common term in RxJava community

https://github.com/ReactiveX/RxJava/wiki/Combining-Observables

artem-zinnatullin · 2018-03-22T15:16:32Z

README.md

+The dataflows in RxJava consist of a source, zero or more intermediate steps followed by a data consumer or combinator step (where the step is responsible to consume the dataflow by some means):
+
+```java
+source.operator1().operator2().operator3().subscribe(consumer);


Here we see "operator" instead of "combinator", so something should be changed for consistency I guess

Here operators are the steps, the combinator refers to flatMap.

artem-zinnatullin · 2018-03-22T15:22:57Z

README.md

+  .subscribe(consumer)
+```
+
+#### Objects in motion


Never heard "Objects in motion" used to describe RxJava streams

https://github.com/reactive-streams/reactive-streams-jvm#glossary

Can't come up with good alternative atm, something along with "Dataflow" could work

I had to encompass all the terms below without repeating them in the title. This felt like a nice encompassing term.

yeah I understand, up2u of course

But just in case, headers in markdown can be clicked and used in urls, so changes in future will break existing urls

That's why I decided to comment it even though I don't have a good replacement option atm

I'll try to remember and add hidden anchors <a name="objects-in-motion"></a> if the time comes.

artem-zinnatullin · 2018-03-22T15:34:39Z

README.md

+flow.subscribe(System.out::println)
+````
+
+This is when the **subscription side-effects** are triggered (see `doOnSubscribe`). Some sources block or start emitting items right away in this state.


Maybe reword to something like:

"Typically in this state source starts synchronous or asynchronous work to prepare data to be emitted."

?

I think referring to "block" and "emitting" is more appropriate in a getting started guide.

artem-zinnatullin · 2018-03-22T15:38:22Z

README.md

+
+This is when the **subscription side-effects** are triggered (see `doOnSubscribe`). Some sources block or start emitting items right away in this state.
+
+#### Runtime


I know it's subjective, but Runtime reads as noun, an object here rather than set of states in time.

Maybe change to "Run-time"?

"“Runtime”, “run time”, and “run-time”": https://english.stackexchange.com/a/197688

I think we need a native English speaker for this.

2.x: Expand the Getting Started

c3d15c6

akarnokd added Documentation 2.x labels Mar 22, 2018

akarnokd added this to the 2.2 milestone Mar 22, 2018

vanniktech approved these changes Mar 22, 2018

View reviewed changes

Some text got accidentally deleted

d233b66

vanniktech approved these changes Mar 22, 2018

View reviewed changes

artem-zinnatullin reviewed Mar 22, 2018

View reviewed changes

akarnokd merged commit fd47265 into ReactiveX:2.x Mar 23, 2018

akarnokd deleted the GettingStartedExpansion branch March 23, 2018 08:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

2.x: Expand the Getting Started #5926

2.x: Expand the Getting Started #5926

akarnokd commented Mar 22, 2018

codecov bot commented Mar 22, 2018 •

edited

Loading

akarnokd commented Mar 22, 2018

vanniktech Mar 22, 2018

akarnokd Mar 22, 2018

akarnokd Mar 22, 2018

artem-zinnatullin Mar 22, 2018

artem-zinnatullin Mar 22, 2018

akarnokd Mar 22, 2018

artem-zinnatullin left a comment

artem-zinnatullin Mar 22, 2018

akarnokd Mar 22, 2018

artem-zinnatullin Mar 22, 2018

akarnokd Mar 22, 2018

artem-zinnatullin Mar 22, 2018

akarnokd Mar 22, 2018

artem-zinnatullin Mar 22, 2018

akarnokd Mar 22, 2018

artem-zinnatullin Mar 22, 2018

akarnokd Mar 22, 2018

artem-zinnatullin Mar 22, 2018

akarnokd Mar 22, 2018

artem-zinnatullin Mar 22, 2018

akarnokd Mar 22, 2018

		The dataflows in RxJava consist of a source, zero or more intermediate steps followed by a data consumer or combinator step (where the step is responsible to consume the dataflow by some means):

		```java


		#### Upstream, downstream

		The dataflows in RxJava consist of a source, zero or more intermediate steps followed by a data consumer or combinator step (where the step is responsible to consume the dataflow by some means):


		This is when the subscription side-effects are triggered (see `doOnSubscribe`). Some sources block or start emitting items right away in this state.

		#### Runtime

2.x: Expand the Getting Started #5926

2.x: Expand the Getting Started #5926

Conversation

akarnokd commented Mar 22, 2018

codecov bot commented Mar 22, 2018 • edited Loading

Codecov Report

akarnokd commented Mar 22, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

artem-zinnatullin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented Mar 22, 2018 •

edited

Loading