Update documentation/comments for `connect()` ref blocking

[MattBrittan]

Update documentation/comments to clarify when the connect() function returns. The function returns after transmitting the CONNECT packet but before the CONNACK is received/processed (this is done in the network loop). There are a number of issues (both on github and stack overflow) caused by an expectation that the connection is fully established when connect() returns.

As per discussion in issue #521