Rxdart: Differences of RxDart and Rx standard could be explicit in the first page.

[BugsBunnyBR]

What's up doc?
I know I am late for this talk (#88 #95), but as this repo still is in the ReactiveX org, the differences between standard Rx implementation and RxDart implementation (and therefore Dart Streams) should be in the README right after the lib name.

A good start point is the Observable class link, but besides that it seems there is no other place to look at.
I tried to Google the differences and the best I could find are the threads above and the Observable class.

All my points below are to say that newcomers to Dart will look at RxDart before looking at Streams and not the other way around. I have been looking at flutter samples, I see a Stream, a Sink or a PublishSubject and I think they are all from RxDart lib.

Some pain points and suggestions:

• What are the differences between an Observable and an Stream? Just the added methods? If so, how about to make it explicit in the README?

• How to create an Observable from different sources ( this link was super useful ) I know there are very similar samples in the stream docs but they don't show the little bit that teach's how to make it an Observable. The README says that I can create an Observable from a stream but don't show how to create a stream[*]. One way to improve on this is to improve the README sample showing the interop between Streams and Observables (how to create a stream from Observables and vice-versa with a full sample showing more ways). A sample just for that could do the work.

• How a PublishSubject, ReplaySubject, BehaviorSubject or any other Observable can be related to a StreamController? Some sample showing the super powers (when to use in a practical world) of pause and resume would be great.

• Is it possible to work with RxDart without using the Dart Stream directly ? Like StreamController, Sync, Stream classes? Because that is just more stuff to learn, if someone could can use stuff they already knows it would be easier to get started.

• In the samples folder use stream/future in multiple places to create an Observable, but don't show how to create am Observable from zero. I mean, is it possible to create and Observable and just send the commands onNext, onError and onComplete?

Note that all my questions are meant to highlight the differences and try to explain why this or that approach is better. At the same time that you explain how RxDart is different from standard Rx implementations you are teaching newcomers about the dart streams API.

[*] After very little time coding in dart I see how the streams API is integrated with the lang and libs, but newcomers don't know that.

Sorry if I seem impolite at some point, my english is not perfect.

That is all folks.

[brianegan]

Hey there :) Thanks for writing in and letting us know about parts of the lib that could be improved.

Sorry if I seem impolite at some point, my english is not perfect.

No worries at all! Appreciate the feedback.

What are the differences between an Observable and an Stream? Just the added methods? If so, how about to make it explicit in the README?

The first line of the README states: "Google Dart comes with a very decent Streams API out-of-the-box; rather than attempting to provide an alternative to this API, RxDart adds functionality on top of it."

Furthermore, just below the example, the first part of the Observable docs reads:

RxDart's Observables extends the Stream class. This has two major implications:
* All methods defined on the Stream class exist on RxDart's Observables as well.
* All Observables can be passed to any API that expects a Dart Stream as an input.
* Additional important distinctions are documented as part of the Observable class

Finally, the Observable class & operators are simple wrappers around Stream and StreamTransformer classes. All underlying implementations can be used free of the Observable class, and are exposed in their own libraries. They are linked to below.

That was our attempt at being explicit, but it sounds like we failed in that attempt, haha :P Is the placement of those docs the problem, or do they not explain what you're hoping for?

In the samples folder use stream/future in multiple places to create an Observable, but don't show how to create am Observable from zero. I mean, is it possible to create and Observable and just send the commands onNext, onError and onComplete?

Good call... we could add docs for this, and I think it might make sense to go forward with https://github.com/ReactiveX/rxdart/issues/185.

Thanks again. It sounds like we still have a bit of work to do around documentation!

[BugsBunnyBR]

The first line of the README states: "Google Dart comes with a very decent Streams API out-of-the-box; rather than attempting to provide an alternative to this API, RxDart adds functionality on top of it."

What does it means in practice ? I read it and thought: "Ok, they used something from the lang as base and extended it.". But they kept the Rx behavior right? I will read the READMEs sample and them my mind already forgot about the dart stream thing, because my focus went to the Rx thing.
I did not even noticed the class list below the sample.

How about something like:

Pay Attention: We don't follow the Rx Standards in these cases:

Table with cases and differences

| Situation | Rx Standards | RxDart | Dart Streams |
| ------------- |------------- | ------------- | ------------- |
| An error is raised | Stop emissions | May cancel[1] | I don't know |
| Cold Observables | Multiple subscribers | Single subscriber | Single subscriber |
| Dart native support | No | Yes |Yes |
| Is {Publish, Behavior, Replay}Subject hot? | No | Yes[2] | Look at StreamController docs |
| Single/Maybe/Complete ? | Yes | No, but PRs are welcome | No |
| Support back pressure| Yes| I don't know if applicable | I don't know if applicable |
| Can emit null? | No| I don't know | I don't know |
| Sync by default | Yes | No | No |
| Has Sink | No| Yes[3] | Yes[3] |
| Can pause/resume a subscription*? | No | Yes[4] | Yes[4] |

[1] When ....
[2] Because... It will emit null by default?
[3] Read more about it here(link)
[4] Read more about it here(link)

• I don't if subscription is the right word here.

  As I said, the docs suppose the people reading it at familiar with Streams API. When I think (I guess) people will come here thinking it is familiar with Rx APIs. Very little matter that it is well integrated with all Dart eco system. I want to know about how does this fits in the Rx eco system.

Maybe something like a FAQ can replace the table or add more infos. I just don't think people are eager to read long class docs when trying something they think they are familiar.

FAQ

Why not to follow the Rx standards?

Dart has Streams, streams are nice. Come with us, join the Dart force.

is there anything like Streams in other langs?

Maybe in Java 8...
### Should we call this RxDart or something else?
Meeh, this is fine. Just make it clear the differences... People will like it after they know it.

All the things I wrote above makes sense to make to exist right after the lib name that have Rx in it is in the ReactiveX org... not in the dartlang org or darlang community org...

[BugsBunnyBR]

Ahh just adding this video to the README also may help. :-)

[frankpepermans]

We could start the readme stating that you should get comfy with Dart Streams first, provide some links etc...

[anaisbetts]

@BugsBunnyBR This chart was super helpful!! A few small corrections, Subjects in Rx are indeed Hot (there is no effect to subscribing, it just adds you to a list), and Observables can emit Null (RxJava 2.x is the only Rx implementation that is Null Hating). Rx Observables also don't support backpressure out of the box usually (this is also an RxJava Thing)

[larssn]

join the Dart side.

@BugsBunnyBR Fixed

[brianegan]

Thanks again for all of the feedback! This has been added to the next version with Extension methods.