Clarify Q{Abstract,Local}Socket::waitForDisconnected() documentation

Make it clear that the functions will return false if the socket was already
disconnected.

Fix the QLocalSocket example snippet to handle that case correctly by checking
state() before attempting to wait.

Fixes: QTBUG-50711
Change-Id: I4ab4062446a0041a35a3a1d65a19202ffa103298
Reviewed-by: Alex Trotsenko <alex1973tr@gmail.com>
Reviewed-by: Mårten Nordheim <marten.nordheim@qt.io>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>

src/network/doc/snippets/code/src_network_socket_qabstractsocket.cpp

@@ -57,9 +57,10 @@ if (socket->waitForConnected(1000))
 
 //! [1]
 socket->disconnectFromHost();
-    if (socket->state() == QAbstractSocket::UnconnectedState ||
-        socket->waitForDisconnected(1000))
+if (socket->state() == QAbstractSocket::UnconnectedState
+    || socket->waitForDisconnected(1000)) {
         qDebug("Disconnected!");
+}
 //! [1]
 
 

src/network/doc/snippets/code/src_network_socket_qlocalsocket_unix.cpp

@@ -57,6 +57,8 @@ if (socket->waitForConnected(1000))
 
 //! [1]
 socket->disconnectFromServer();
-if (socket->waitForDisconnected(1000))
+if (socket->state() == QLocalSocket::UnconnectedState
+    || socket->waitForDisconnected(1000)) {
     qDebug("Disconnected!");
+}
 //! [1]

src/network/socket/qabstractsocket.cpp

@@ -2359,11 +2359,12 @@ bool QAbstractSocket::waitForBytesWritten(int msecs)
 }
 
 /*!
-    Waits until the socket has disconnected, up to \a msecs
-    milliseconds. If the connection has been disconnected, this
-    function returns \c true; otherwise it returns \c false. In the case
-    where it returns \c false, you can call error() to determine
-    the cause of the error.
+    Waits until the socket has disconnected, up to \a msecs milliseconds. If the
+    connection was successfully disconnected, this function returns \c true;
+    otherwise it returns \c false (if the operation timed out, if an error
+    occurred, or if this QAbstractSocket is already disconnected). In the case
+    where it returns \c false, you can call error() to determine the cause of
+    the error.
 
     The following example waits up to one second for a connection
     to be closed:

src/network/socket/qlocalsocket.cpp

@@ -287,11 +287,12 @@ QT_BEGIN_NAMESPACE
 /*!
     \fn bool QLocalSocket::waitForDisconnected(int msecs)
 
-    Waits until the socket has disconnected, up to \a msecs
-    milliseconds. If the connection has been disconnected, this
-    function returns \c true; otherwise it returns \c false. In the case
-    where it returns \c false, you can call error() to determine
-    the cause of the error.
+    Waits until the socket has disconnected, up to \a msecs milliseconds. If the
+    connection was successfully disconnected, this function returns \c true;
+    otherwise it returns \c false (if the operation timed out, if an error
+    occurred, or if this QLocalSocket is already disconnected). In the case
+    where it returns \c false, you can call error() to determine the cause of
+    the error.
 
     The following example waits up to one second for a connection
     to be closed: