documentation: add description for connected() and status()

[mcspr]

ref. the original PR and the discussion
#4626
#6701

as mentioned in the #8327 (comment)

(I have yet to check the readthedocs rendering)

[mcspr]

And as #6701 already mentioned, this is somewhat different for the secure variant:

Arduino/libraries/ESP8266WiFi/src/WiFiClientSecureBearSSL.cpp

Lines 259 to 264 in 9d024d1

	uint8_t WiFiClientSecureCtx::connected() {
	if (available() || (_clientConnected() && _handshake_done && (br_ssl_engine_current_state(_eng) != BR_SSL_CLOSED))) {
	return true;
	}
	return false;
	}

But, it's unclear whether this refers to the WiFiClient interface or the basic-socket WiFiClient class

[d-a-v]

To summarize the need for this change:
In the case where connected() was returning true when the connection was closed by peer but data were still available for read in receive buffers, sketches found themselves allowed to write something which obviously leaded to an error when they did.
Removing the available() test from connected() could stop this behavior.
The downside of this change is that available() has to be checked even if connected() is false.
... and if this (half-closed by peer) connection is fully closed by sketch before reading remaining data, peer complains because its data will never be read. The server example in doc allows to reproduce this, the matching posix error on the peer side shows a 'Broken pipe' if I remember well.

So indeed I think this PR should also remove the available() part of TLS's connected() function for coherency with WiFiClient implementation. Good catch.

But, it's unclear whether this refers to the WiFiClient interface or the basic-socket WiFiClient class

The TLS context is supposed to match the WiFiClient class.

[mcspr]

The TLS context is supposed to match the WiFiClient class.

...true, but also note that it is used internally. can update, but it may be better suited as a separate patch

Will update with the 'connected' part with the reasoning, seems like a good place to also explain things

[d-a-v]

but also note that it is used internally.

Right!
In those places, one must check whether testing available() must be added next to connected(), or replace it.

[d-a-v]

It will return true when the client is status() == ESTABLISHED or available() == true, but will return false when the status() == CLOSED.

According to current code, it will return false if the connection is closed, regardless available() result,
meaning "writing is not allowed".

available() can still be checked to tell if something has been received but kept unread.

Arduino/libraries/ESP8266WiFi/src/WiFiClient.cpp

Lines 329 to 335 in f401f08

	uint8_t WiFiClient::connected()
	{
	if (!_client || _client->state() == CLOSED)
	return 0;
	return _client->state() == ESTABLISHED || available();
	}