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 ||
+if (socket->state() == QAbstractSocket::UnconnectedState
-        socket->waitForDisconnected(1000))
+    || 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
+    Waits until the socket has disconnected, up to \a msecs milliseconds. If the
-    milliseconds. If the connection has been disconnected, this
+    connection was successfully disconnected, this function returns \c true;
-    function returns \c true; otherwise it returns \c false. In the case
+    otherwise it returns \c false (if the operation timed out, if an error
-    where it returns \c false, you can call error() to determine
+    occurred, or if this QAbstractSocket is already disconnected). In the case
-    the cause of the error.
+    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
+    Waits until the socket has disconnected, up to \a msecs milliseconds. If the
-    milliseconds. If the connection has been disconnected, this
+    connection was successfully disconnected, this function returns \c true;
-    function returns \c true; otherwise it returns \c false. In the case
+    otherwise it returns \c false (if the operation timed out, if an error
-    where it returns \c false, you can call error() to determine
+    occurred, or if this QLocalSocket is already disconnected). In the case
-    the cause of the error.
+    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: