- add availability statements for some of the new APIs

- lots of general cleanup

Doc/lib/libsocket.tex

@@ -156,13 +156,14 @@ supported on this platform.
 \versionadded{2.3}
 \end{datadesc}
 
-\begin{funcdesc}{getaddrinfo}{host, port\optional{, family, socktype, proto, flags}}
-
+\begin{funcdesc}{getaddrinfo}{host, port\optional{, family\optional{,
+                              socktype\optional{, proto\optional{,
+                              flags}}}}}
 Resolves the \var{host}/\var{port} argument, into a sequence of
 5-tuples that contain all the necessary argument for the sockets
 manipulation. \var{host} is a domain name, a string representation of
 IPv4/v6 address or \code{None}.
-\var{port} is a string service name (like \code{``http''}), a numeric
+\var{port} is a string service name (like \code{'http'}), a numeric
 port number or \code{None}.
 
 The rest of the arguments are optional and must be numeric if
@@ -171,15 +172,16 @@ string or \code{None}, you can pass \code{NULL} to the C API.  The
 \function{getaddrinfo()} function returns a list of 5-tuples with
 the following structure:
 
-\code{(\var{family}, \var{socktype}, \var{proto}, \var{canonname}, \var{sockaddr})}.
+\code{(\var{family}, \var{socktype}, \var{proto}, \var{canonname},
+      \var{sockaddr})}
 
 \var{family}, \var{socktype}, \var{proto} are all integer and are meant to
 be passed to the \function{socket()} function.
 \var{canonname} is a string representing the canonical name of the \var{host}.
-It can be a numeric IPv4/v6 address when \code{AI_CANONNAME} is specified
+It can be a numeric IPv4/v6 address when \constant{AI_CANONNAME} is specified
 for a numeric \var{host}.
 \var{sockaddr} is a tuple describing a socket address, as described above.
-See \code{Lib/httplib.py} and other library files
+See the source for the \refmodule{httplib} and other library modules
 for a typical usage of the function.
 \versionadded{2.2}
 \end{funcdesc}
@@ -206,10 +208,11 @@ is an IPv4 address itself it is returned unchanged.  See
 
 \begin{funcdesc}{gethostbyname_ex}{hostname}
 Translate a host name to IPv4 address format, extended interface.
-Return a triple \code{(hostname, aliaslist, ipaddrlist)} where
-\code{hostname} is the primary host name responding to the given
-\var{ip_address}, \code{aliaslist} is a (possibly empty) list of
-alternative host names for the same address, and \code{ipaddrlist} is
+Return a triple \code{(\var{hostname}, \var{aliaslist},
+\var{ipaddrlist})} where
+\var{hostname} is the primary host name responding to the given
+\var{ip_address}, \var{aliaslist} is a (possibly empty) list of
+alternative host names for the same address, and \var{ipaddrlist} is
 a list of IPv4 addresses for the same interface on the same
 host (often but not always a single address).
 \function{gethostbyname_ex()} does not support IPv6 name resolution, and
@@ -322,11 +325,10 @@ no-op; otherwise, it performs a 2-byte swap operation.
 \begin{funcdesc}{inet_aton}{ip_string}
 Convert an IPv4 address from dotted-quad string format (for example,
 '123.45.67.89') to 32-bit packed binary format, as a string four
-characters in length.
-
-Useful when conversing with a program that uses the standard C library
-and needs objects of type \ctype{struct in_addr}, which is the C type
-for the 32-bit packed binary this function returns.
+characters in length.  This is useful when conversing with a program
+that uses the standard C library and needs objects of type
+\ctype{struct in_addr}, which is the C type for the 32-bit packed
+binary this function returns.
 
 If the IPv4 address string passed to this function is invalid,
 \exception{socket.error} will be raised. Note that exactly what is
@@ -340,16 +342,14 @@ support.
 
 \begin{funcdesc}{inet_ntoa}{packed_ip}
 Convert a 32-bit packed IPv4 address (a string four characters in
-length) to its standard dotted-quad string representation
-(for example, '123.45.67.89').
-
-Useful when conversing with a program that uses the standard C library
-and needs objects of type \ctype{struct in_addr}, which is the C type
-for the 32-bit packed binary this function takes as an argument.
+length) to its standard dotted-quad string representation (for
+example, '123.45.67.89').  This is useful when conversing with a
+program that uses the standard C library and needs objects of type
+\ctype{struct in_addr}, which is the C type for the 32-bit packed
+binary data this function takes as an argument.
 
 If the string passed to this function is not exactly 4 bytes in
 length, \exception{socket.error} will be raised.
-
 \function{inet_ntoa()} does not support IPv6, and
 \function{getnameinfo()} should be used instead for IPv4/v6 dual stack
 support.
@@ -358,37 +358,37 @@ support.
 \begin{funcdesc}{inet_pton}{address_family, ip_string}
 Convert an IP address from its family-specific string format to a packed,
 binary format.
-
-Supported values for address_family are currently \constant{AF_INET}
-and \constant{AF_INET6}. 
-
 \function{inet_pton()} is useful when a library or network protocol calls for
 an object of type \ctype{struct in_addr} (similar to \function{inet_aton()})
 or \ctype{struct in6_addr}.
 
-If the IP address string passed to this function is invalid,
+Supported values for \var{address_family} are currently
+\constant{AF_INET} and \constant{AF_INET6}.
+If the IP address string \var{ip_string} is invalid,
 \exception{socket.error} will be raised. Note that exactly what is valid
 depends on both the value of \var{address_family} and the underlying
 implementation of \cfunction{inet_pton()}.
+
+Availability: \UNIX{} (maybe not all platforms).
 \versionadded{2.3}
 \end{funcdesc}
 
 \begin{funcdesc}{inet_ntop}{address_family, packed_ip}
-Convert a packed IP address (a string of some number of characters) to its
-standard, family-specific string representation (for example, '7.10.0.5' or
-'5aef:2b::8')
-
-Supported values for address_family are currently \constant{AF_INET}
-and \constant{AF_INET6}. 
-
+Convert a packed IP address (a string of some number of characters) to
+its standard, family-specific string representation (for example,
+\code{'7.10.0.5'} or \code{'5aef:2b::8'})
 \function{inet_ntop()} is useful when a library or network protocol returns
 an object of type \ctype{struct in_addr} (similar to \function{inet_ntoa()})
 or \ctype{struct in6_addr}.
 
-If the string passed to this function is not the correct length for the
-specified address family, \exception{ValueError} will be raised.
-A \exception{socket.error} is raised for errors from the call to
+Supported values for \var{address_family} are currently
+\constant{AF_INET} and \constant{AF_INET6}.
+If the string \var{packed_ip} is not the correct length for the
+specified address family, \exception{ValueError} will be raised.  A
+\exception{socket.error} is raised for errors from the call to
 \function{inet_ntop()}.
+
+Availability: \UNIX{} (maybe not all platforms).
 \versionadded{2.3}
 \end{funcdesc}
 
@@ -616,7 +616,7 @@ immediately will fail.
 \begin{methoddesc}[socket]{setsockopt}{level, optname, value}
 Set the value of the given socket option (see the \UNIX{} manual page
 \manpage{setsockopt}{2}).  The needed symbolic constants are defined in
-the \module{socket} module (\code{SO_*} etc.).  The value can be an
+the \module{socket} module (\constant{SO_*} etc.).  The value can be an
 integer or a string representing a buffer.  In the latter case it is
 up to the caller to ensure that the string contains the proper bits
 (see the optional built-in module