Clarify social API behavior acts as expected in interface comments

[iislucas]

Open questions, should the social provider guarantee the natural/obvious things for ordering of events:

1 * onMessage and onClientState, and onUserProfile events only happen after the login promise returns.

2 * onMessage and onUserProfile events only happen after a onClientState event with clientId having its state set to ONLINE*, and before onClientState event happens setting the state of OFFLINE.

3 * onClientState with the same clientId as login returned happens if/when the social provider is disconnected? Or Should we introduce a new onDisconnected event?

[ryscheng]

I'm inclined not to add more guarantees. For the second one, why would it be the case that you can't receive the user's profile while they're offline? It's actually quite common to get a roster without the user actually being online.
The server could also queue messages to be sent after the user has already gone offline.

For the first one, why only register handlers for events after the login fulfill gets called?

[iislucas]

Either way, we should clarify in the comments. :)

Update on (2) from in-person discussion:

if a user sets their state of offline, but write you a message, you should get the message. Potentially, you want the same thing for onUserProfile. So we agreed to clarify that (2) is not guaranteed!

But bad things happen with no guarantees:

• no way to know when social provider is disconnected to e.g. change UI state to logged out so that user doesn't think messages they are sending will ever go anywhere. (fixed by 3)
• with (3) but no guarantees, use can get logged out before the login promise returns.
• without (1) any intermediate data structures made upon return of the promise may not be ready. I don't feel very strongly about this if we document it, but I do have a preference for the guarantee as I don't see any use-case for it not being there, and it's more natural to get messages from a service you are connected to than one you are not connected to (Right now, I can't think of any other network/social interface that does not guarantee this).

[agallant]

This is an old issue, but probably worth ensuring we resolve it along with #273.