CURLOPT_PORT.3: We discourage using this option

Closes #8941

diff --git a/docs/libcurl/opts/CURLOPT_PORT.3 b/docs/libcurl/opts/CURLOPT_PORT.3
index bc70ba795e93c7d373dd8160cdd53177b354cda5..a5a065617de4e515e1a68c4b706f9cb905276f4b 100644 (file)
--- a/docs/libcurl/opts/CURLOPT_PORT.3
+++ b/docs/libcurl/opts/CURLOPT_PORT.3
@@ -30,6 +30,9 @@ CURLOPT_PORT \- remote port number to connect to
 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PORT, long number);
 .fi
 .SH DESCRIPTION
+We discourage using this option since it's scope is not obvious and hard to
+predict. Set the preferred port number in the URL instead.
+
 This option sets \fInumber\fP to be the remote port number to connect to,
 instead of the one specified in the URL or the default port for the used
 protocol.
@@ -40,7 +43,8 @@ application to override that.
 While this option accepts a 'long', a port number is usually a 16 bit number
 and therefore using a port number over 65535 will cause a runtime error.
 .SH DEFAULT
-By default this is 0 which makes it not used.
+By default this is 0 which makes it not used. This also makes port number zero
+impossible to set with this API.
 .SH PROTOCOLS
 Used for all protocols that speak to a port number.
 .SH EXAMPLE