Some real documentation

[fresheneesz]

So, it would be great if this project had documentation. Not examples. Not halfassed documentation of a couple random things, but actual docs. Like, why doesn't the documentation on github mention volatile sending?

I'm probably willing to write some if you guys are willing to accept it, so please give me some guidelines that will help me ensure my edits will be accepted.

[cendrizzi]

This would be a nice project and I agree with the motivations. The examples are great but a real API like documentation would be even better. For the most part socket.io is nicely designed and very approachable but when you get beyond that it's hard to find the information you need.

[cendrizzi]

Going further it would be nice if this could be a community driven project so Guille could focus on the core stuff.

[xbojer]

I'd be more than happy to read socket.io documentation.

Samples on web page described as "documentation" are good for the first 5 minutes you do something with socket.io in your project. After that are only hours spent on searching and reading web just to get something that should be stated in documentation. This project's lack of documentation is real time waster!

[kiriantello]

+1

[honi]

+1

[vicary]

+1

This project needs motivations.

[cendrizzi]

Anyone interested in helping with a document project to alleviate this with me? I have way too much resting on socket.io and at this point am going through the code line by line to ensure I really understand everything. I know 1.0 is around the corner someday but no one seems to know when and there are no guarantees that it won't have a bugs anyway given how tremendous of a break it is.

Therefore people like me will have need of the 0.9 codebase for some time and that means some real docs and understanding and hopefully more shared knowledge from them.

Going through the code makes me want to document this stuff so I can go back and understand things if I run into something

Hopefully such a project would get Guillermo's blessing. Guillermo?

Such a project needs to document the basics, some common use cases, and best practices for scaling, etc.

[rauchg]

As far as the API goes, I would like it to follow the style of engine.io,
that clearly documents each event, property and method:
https://github.com/LearnBoost/engine.io#api

On Sat, Nov 16, 2013 at 3:15 PM, cendrizzi notifications@github.com wrote:

Anyone interested in helping with a document project to alleviate this
with me? I have way too much resting on socket.io and at this point am
going through the code line by line to ensure I really understand
everything. I know 1.0 is around the corner someday but no one seems to
know when and there are no guarantees that it won't have a bugs anyway
given how tremendous of a break it is.

Therefore people like me will have need of the 0.9 codebase for some time
and that means some real docs and understanding and hopefully more shared
knowledge from them.

Going through the code makes me want to document this stuff so I can go
back and understand things if I run into something

Hopefully such a project would get Guillermo's blessing. Guillermo?

Such a project needs to document the basics, some common use cases, and
best practices for scaling, etc.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/1318#issuecomment-28632296
.

Guillermo Rauch
Cloudup CTO
http://devthought.com

[cendrizzi]

That was fast :).

Guillermo, so would this be helpful if I updated the current wiki? Following the engine.io lead?

[cendrizzi]

Temporarily I've created a project to update my docs in progress. Part of this is because I don't actually know how the wiki and stuff works for Github so I just created a new project until I feel this is ready to be included as part of the official docs.

See here: https://github.com/cendrizzi/socket.io-docs/blob/master/README.md

If you want to contribute let me know.

Right now they aren't done. I was kind of in two minds while writing them. In one way I was trying to learn all the code so I documented some stuff that is considered private and would only be appropriate for core developers. On the other hand I did leave some private methods off after I realized I should probably not document all the private stuff.

Anyway it does follow the engine.io spec and I know I would have like something like this when I started with socket.io.