Update official documentation

[gsklee]

Please update the official documentation on the website. A lot of clues are hinting that the documentation is either quite old or not very well-maintained. For example I've found links referring to https://github.com/Automattic/engine.io instead of https://github.com/socketio/engine.io, as well as example codes detailing outdated Express usage.

[jhohlfeld]

Yes please, I had to dig into the code to find out about the API for client and server quite often! It seems that the docs are not reflecting all aspects of the API's components:

• Part of my confusion may be well to the fact, that parts are documented in the engine.io repo instead. For instance, methods of the Socket object are not listed in the Client API docs but in engine.io' README :thinking_face:

[pherrymason]

Mainly, the whole website seems unmantained:

• Technical Features: There is no list of features socket.io gives me. Why should I use this library instead of others? Should I only trust the followers this repo has?
  Today I stumbled into this stackoverflow question describing a list of alleged features that I cannot see in the website.
• Demos: doesn't work for me (GET http://chat.socket.io/socket.io/socket.io.js net::ERR_INCOMPLETE_CHUNKED_ENCODING)
• Chat: Is it still active? The form to be able to access the slack community seems to do nothing.
• Documentation: As @gsklee and @jhohlfeld said, a lot is missing. I feel like there are a lot of gaps in it:
  • The overview section refers to Engine.IO if user doesn't care about reconnection logic, but there is no info on the reconnection system implemented by Socket.io.
  • As there is no feature list, one has to struggle to find what is possible and what is not if not explained directly by documentation. For example: Is there a way to list namespaces? Rooms? clients? Can I enable/disable transportation layers?
  • Documentation talks about rooms, the only example in the web is how to write a chat... Is socket.io headed to only develop chats? (I know it's not, but it looks so).
  • Features explained lightly in one side, are missing their required counter part partly or completely. For example: changing the default 'socket.io' path in the connection url is explained in Server side (path option), but missing in Client side.
  • Incomplete list of options accepted by Server and Client.
  • Reading issues seems to me that there is a lot of undocumented behaviour not included in documentation.
  • API's: References to stuff like Adapter, Manager that has no own section with a deep explanation of them.
  • Links in the API to https://github.com/socket.io/socket.io-adapter 404'd
  • Client API: Missing a complete list of accepted options in the constructor. One can only discover them by looking at source code.
  • In the rooms section in the API, it says that an Adapter handles the logic of joining/leaving a room. This is not explained in the "Namespaces / Rooms" section of the docs.

Please, all this intends to be as constructive as possible.

[darrachequesne]

That issue was closed automatically. Please check if your issue is fixed with the latest release, and reopen if needed (with a fiddle reproducing the issue if possible).

[gsklee]

@darrachequesne Automatically closed due to inactivity? What does this even suppose to mean? Please, bravely face the fact that the project's online doc is a dire mess and in need of some serious love from your core team. The library contains a lot of obscure, undocumented behaviors that require end users like us to devote a great deal of time ploughing through the source code to get some really basic ideas, let alone help documenting them; you the core team is equipped with the best knowledge to handle this task, but it never gets any real attention from the core members. That doesn't mean you can pretend this issue is no longer here and you can close it. The end users still deserve a working, up-to-date copy of the docs!

[creole]

@gsklee Did you see #2784 and #2815, among others?

[darrachequesne]

@gsklee so that issue is alive, thanks!

[darrachequesne]

Features section: #2824