Documentation (in particular Observable.webSocket)

[timjacobi]

Hi Guys,

First of all congrats on releasing the final version, I appreciate the work everyone has put into this project as I've been closely following. Now that the final version is released I was hoping to find some more complete API documentation. In this case I was looking to create an observable from web sockets.

I went to the API docs which tell me I need to pass urlConfigOrSource but I could not figure out how to set it up, am I missing something?
Moving on Observable.webSocket returns a WebSocketSubject so I tried to find out how to use it. All the API docs tell me is We need this JSDoc comment for affecting ESDoc.

Just to compare Observable.fromPromise has a neat little example that tells me how to use it.

I would really like to fully start using RxJS 5 when we build our next product but the lack of documentation prevents us from doing so. If we were to use it then I'm sure we would also contribute if we find bugs as we go along.

Am I missing an important piece here?
Are there any examples elsewhere?
How can I get involved to help improving the docs?

Again thanks for this great library.

[kwonoj]

Yes, while it is released version it still lacks some of the documentation in detail, need to be improved over time. If you're using TypeScript in codebases, most of type comes with the inference that you can get it immediately (i.e config interface you mentioned: https://github.com/ReactiveX/rxjs/blob/master/src/observable/dom/WebSocketSubject.ts#L13) but that isn't applicable for all cases since it's TypeScript only.

For now, if you find some of docs are missing and looking for concise examples of code snippet, unit test in repo provides immediate workarounds. For example, you can find several approach of constructing websocketsubject in test case (https://github.com/ReactiveX/rxjs/blob/master/spec/observables/dom/webSocket-spec.ts#L226) with its usages.

It is hugely appreciated to have contribution to improve document - first you can check general contribution guideline here (https://github.com/ReactiveX/rxjs/blob/master/CONTRIBUTING.md) and use other documented codebase as reference (https://github.com/ReactiveX/rxjs/blob/master/src/operator/filter.ts for example).

[benlesh]

The bottom line here is that we need to add documentation around WebSocketSubject. Thanks @timjacobi for bringing this back to our attention. I think we should prioritize documentation as well.

[timjacobi]

@kwonoj Thanks for pointing out the tests, I was actually able to infer a lot of stuff from there 👍

[jrgleason]

It would be nice if we could add more details about how to test this too. I looked at https://github.com/ReactiveX/rxjs/blob/9b428d7778ae8ac35c729e66a238ce97698a252e/spec/observables/dom/webSocket-spec.ts but I couldn't really figure it out.

[luillyfe]

Hi guys, any advance in this topic ? because I got a proposal, it is pretty straightforward (a news feed) but it shows a real use case where we can use websocket subject.

https://github.com/luillyfe/rxjs-websockets/tree/features/news-feed.

Reviews so Welcome!

[luillyfe]

Here I come with Multiplexing example (It has News and Chat),

https://github.com/luillyfe/rxjs-websockets/tree/features/multiplexing

I want to hear your opinions.

[luillyfe]

@dalu not sure what you mean by that. Do you mind to explain it a little better ?

[inf3cti0n95]

@dalu in the multiplex() method, for message filter the filter function should return a Boolean value (true or false). returning True will result in message to pass and return false would filter out the message.

I suggest if you need to have a filter to have no messages to be passed, try out

() => false

I hope this makes it clear.

[inf3cti0n95]

@dalu Oops! My bad!

[inf3cti0n95]

@dalu But then If you do not want to have that sub and unSub methods to fire, why are you even using multiplex? Can't you just use the original webSocket with a filter method? 😅