Documentation about CURL_POLL_REMOVE is a bit misleading #9799
Description
I am using a hiper-style integration of curl with asio. To do this, I set a socket callback using CURLMOPT_SOCKETFUNCTION and a pair of socket open/close callbacks using CURLOPT_OPENSOCKETFUNCTION and CURLOPT_CLOSESOCKETFUNCTION.
I noticed that when sending several requests to an HTTP/1.1 server only a couple of sockets are opened with my OPENSOCKETFUNCTION, which are then used for multiple requests. For each socket I receive several times a socket callback with the what parameter set to CURL_POLL_REMOVE. I believe what is happening is that after each request is completed cURL invokes the socket callback with CURL_POLL_REMOVE, then puts the socket in an idle connection pool, then reuses it for the next request to the same server. This makes sense, but is not what I was expecting from the documentation of CURLMOPT_SOCKETFUNCTION, which says:
CURL_POLL_REMOVE The specified socket/file descriptor is no longer used by libcurl.
Now, the documentation does not say that it won't ever be used again, but it kind of gives that impression. Maybe the documentation could be clarified a bit by saying that cURL might not close that socket and try to use it again later on? Unfortunately there isn't any code example using both CURLMOPT_SOCKETFUNCTION and CURLOPT_OPENSOCKETFUNCTION, and there is not much documentation about their interaction. I was under the impression that a socket would always be closed after CURL_POLL_REMOVE, while clearly this is not the case.