About consistency, deprecations and docs

[UserGalileo]

Documentation Related To Component:

/

Please check those that apply

• typo
• documentation doesn't exist
• documentation needs clarification
• error(s) in example
• needs example

Description Of The Issue

I'd like to talk about some topics which are honestly driving me nuts lately and I think they should be clarified. I found different issues for some of them, but some are quite old and it's not clear what's reliable or not, so forgive me if some of this is already present in other issues, but I think all of this is correlated.

Let's start with deprecations:

Deprecations and misleading docs

The deprecation of resultSelectors was made clear in the codebase, in blog posts and in conferences. But the docs (v6.5.5) are incomplete or misleading: take for example switchMap/mergeMap, the only place it says "depcrecated" is in the "Returns" paragraph of the docs. But why? Why shouldn't we put a visible label on the parameter itself? In order to know what's deprecated or not, I'm doing cmd+f in every page looking for "deprecated" hoping to find something. I know there's a dedicated "Migration" page with this info, but I shouldn't be looking at it for every operator API that I check! Is it going to change in v7 docs?

PS. Little rant (forgive me): in version 6.x resultSelectors were deprecated and everywhere it was said that with the next major version they were going away. It appears that they're still around in v7. Why? I get it, fewer breaking changes, I just found these info to be misleading. And just to make it clear: I love resultSelectors and frankly I don't understand why there was the decision to get rid of them. Don't get me wrong, I understand that they make some "noise" in your codebase, but this noise is just moved in our own projects, where an additional pipe+map for every Inner Observable (I'm talking about flattening operators here) makes the code more difficult to read. I've used them whenever I needed to and so did a lot of my colleagues, and we've always found them useful. Are we sure "almost nobody uses them"? / End of rant :D

Moreover, it appears that with version 6.5 (almost one year ago?) the signatures for forkJoin and combineLatest which don't accept an array have been deprecated. For some reason my IDE never highlighted it, I just thought there was just one more way to use these operators (which would be absolutely fine in my opinion). In the docs, the deprecated signatures (without arrays) are used just everywhere.

Consistency

And since we're deprecating signatures for forkJoin and combineLatest, why shouldn't we deprecate all the similar signatures too? I'm talking about merge, concat & co, if I'm not wrong there's no deprecation warning for these ones. Shouldn't operators be consistent? Am I missing some info? Also, forkJoin accepts a dictionary and I've read that the combineLatest deprecations could be useful also in order to make it eventually accept a dictionary: why eventually? Why don't we deal with it now? It's not a breaking change, it'd be a new feature for these operators and it would be a huge pro not having to remember which operator has the dictionary-signature.

Roadmap

Just a final note: when will we have a clear roadmap? I read an issue some days ago where it was said that this was a nice idea: I think it is absolutely necessary. I had to use Google and Twitter in order to find @benlesh slides at NgConf just to get an idea of the future versions of RxJS :)

I love RxJS and I support it everyday wherever I can: I recently made a video course about it. But in my opinion these issues don't belong to a great product such as this library: they should be clarified as soon as possible. Are we actively working on them? Do you need any help? I just read from the latest slides that "Documentation needs updates", great, but if there was a clear roadmap everything would be easier and it would be easier for us to help.

Thanks!

[jakovljevic-mladen]

Hi there. I am also a fan of RxJS and I agree with you in many cases, consistency should be number one priority for libraries like this. But, I also need to add a note here that this is a library that is maintained solely by the free will (and free time) of it's contributors, at least Ben talked about this in his conference speeches for the core team. So you have to understand that some things may not work at all times.

What you, me and everyone else can do is that we can help. I'm willing to help, especially with the docs. Since you made couple of points here, is there a way you could create separate issues for all of them? I could maybe take some of them and try fix consistency problems. We also need some support from the core team about what and how to do it, and which version to fix. I think v6 will be left out for docs fixes, so it should be made against v7 or v8.

I noticed one thing that could be sorted out (and I will probably create separate ticket for that): in many cases, key building blocks like Observables or Subjects are written with the first capital letter, but there are cases in the docs where this is not the case. I would like if we could achieve this consistency too, either by writing Observable or observable, but sticking with one form in every doc page.