tag some functions as deprecated in docs

docs/ares_get_servers.3

@@ -18,7 +18,7 @@
 .\"
 .TH ARES_GET_SERVERS 3 "5 March 2010"
 .SH NAME
-ares_get_servers, ares_get_servers_ports \- Retrieve name servers from an initialized ares_channel
+ares_get_servers, ares_get_servers_ports \- Retrieve name servers from an initialized ares_channel (deprecated)
 .SH SYNOPSIS
 .nf
 #include <ares.h>
@@ -77,6 +77,9 @@ was invalid.
 .SH AVAILABILITY
 \fBares_get_servers(3)\fP was added in c-ares 1.7.1;
 \fBares_get_servers_ports(3)\fP was added in c-ares 1.11.0.
+.SH NOTES
+As of c-ares 1.24, these functions are deprecated due to their lack of ability
+to store the entire server configuration.  Use \fBares_get_servers_csv(3)\fP.
 .SH AUTHOR
 Implementation of this function and associated library internals are based
 on code, comments and feedback provided in November and December of 2008 by

docs/ares_getsock.3

@@ -17,7 +17,7 @@
 .\"
 .TH ARES_GETSOCK 3 "11 March 2010"
 .SH NAME
-ares_getsock \- get socket descriptors to wait on
+ares_getsock \- get socket descriptors to wait on (deprecated)
 .SH SYNOPSIS
 .nf
 #include <ares.h>
@@ -37,8 +37,8 @@ Socket descriptors will be set in the socket descriptor array pointed to by
 \fIsocks\fP.
 \fInumsocks\fP is the size of the given array in number of ints.
 
-This function can only return information about up to 16 sockets. If more are
+This function can only return information up to 16 sockets. If more are
-in use (however unlikely that is), they are simply not reported back.
+in use, they are simply not reported back.
 .SH RETURN VALUES
 \fBares_getsock\fP returns a bitmask for what actions to wait for on the
 different sockets. The ares.h header file provides these convenience macros to
@@ -52,7 +52,9 @@ extract the information appropriately:
                                          ARES_GETSOCK_MAXNUM)))
 .fi
 .SH NOTES
-This function was added in c-ares 1.3.1
+This function was added in c-ares 1.3.1 and deprecated in c-ares 1.20.0 due to
+the implementation of \fBARES_OPT_MAX_UDP_QUERIES\fP which makes it likely to
+exceed 16 open file descriptors.
 .SH SEE ALSO
 .BR ares_timeout (3),
 .BR ares_fds (3),

docs/ares_set_servers.3

@@ -18,7 +18,7 @@
 .TH ARES_SET_SERVERS 3 "5 March 2010"
 .SH NAME
 ares_set_servers, ares_set_servers_ports \- Initialize name server configuration
-for an ares channel.
+for an ares channel. (deprecated)
 .SH SYNOPSIS
 .nf
 #include <ares.h>
@@ -90,7 +90,7 @@ c-ares library initialization not yet performed.
 .BR ares_init_options (3),
 .BR ares_dup (3)
 
-.SH NOTE
+.SH NOTES
 Deprecated functions as of c-ares 1.24.0 due to inability to set all available
 server options.  Use \fBares_set_servers_csv(3)\fP.