diff --git a/docs/libcurl/curl_multi_socket.md b/docs/libcurl/curl_multi_socket.md
index 5903a1e1fa..490af19c4f 100644
--- a/docs/libcurl/curl_multi_socket.md
+++ b/docs/libcurl/curl_multi_socket.md
@@ -29,8 +29,8 @@ CURLMcode curl_multi_socket(CURLM *multi_handle, curl_socket_t sockfd,
 
 # DESCRIPTION
 
-This function is deprecated. Do not use. See curl_multi_socket_action(3)
-instead.
+This function is deprecated. Use curl_multi_socket_action(3) instead with
+**ev_bitmask** set to 0.
 
 At return, the integer **running_handles** points to contains the number of
 still running easy handles within the multi handle. When this number reaches
@@ -54,9 +54,6 @@ to CURL_SOCKET_TIMEOUT. You can also use the curl_multi_timeout(3) function to
 poll the value at any given time, but for an event-based system using the
 callback is far better than relying on polling the timeout value.
 
-Usage of curl_multi_socket(3) is deprecated, whereas the function is
-equivalent to curl_multi_socket_action(3) with **ev_bitmask** set to 0.
-
 # %PROTOCOLS%
 
 # EXAMPLE
diff --git a/docs/libcurl/curl_multi_socket_all.md b/docs/libcurl/curl_multi_socket_all.md
index 37a605bde3..d7f832b51d 100644
--- a/docs/libcurl/curl_multi_socket_all.md
+++ b/docs/libcurl/curl_multi_socket_all.md
@@ -30,8 +30,8 @@ CURLMcode curl_multi_socket_all(CURLM *multi_handle,
 
 # DESCRIPTION
 
-This function is deprecated. Do not use. See curl_multi_socket_action(3)
-instead.
+This function is deprecated for performance reasons but there are no plans to
+remove it from the API. Use curl_multi_socket_action(3) instead.
 
 At return, the integer **running_handles** points to contains the number of
 still running easy handles within the multi handle. When this number reaches