docs/usocket: getaddrinfo: Describe af/type/proto optional params.

These can be optionally specified, but all ports are expected to be able to
accept them, at the very least ignore, though handling of "type" param
(SOCK_STREAM vs SOCK_DGRAM) is recommended.

1 files changed, 17 insertions, 3 deletions

diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst
index 3ae477a9a..3c8f878f1 100644
--- a/docs/library/usocket.rst
+++ b/docs/library/usocket.rst
@@ -79,19 +79,33 @@ Functions
         # Create DGRAM UDP socket
         socket(AF_INET, SOCK_DGRAM)
 
-.. function:: getaddrinfo(host, port)
+.. function:: getaddrinfo(host, port, af=0, type=0, proto=0, flags=0)
 
    Translate the host/port argument into a sequence of 5-tuples that contain all the 
-   necessary arguments for creating a socket connected to that service. The list of 
-   5-tuples has following structure::
+   necessary arguments for creating a socket connected to that service. Arguments
+   *af*, *type*, and *proto* (which have the same meaning as for `socket()` function)
+   can be used to filter which kind of addresses are returned. If a parameter not
+   specified or zero, all combinations of addresses can be returned (requiring
+   filtering on the user side).
+
+   The resulting list of 5-tuples has the following structure::
 
       (family, type, proto, canonname, sockaddr)
 
    The following example shows how to connect to a given url::
 
       s = usocket.socket()
+      # This assumes that if "type" is not specified, address for
+      # SOCK_STREAM will be returned, which may be not true
       s.connect(usocket.getaddrinfo('www.micropython.org', 80)[0][-1])
 
+   Recommended use of filtering params::
+
+      s = usocket.socket()
+      # Guaranteedly returns address which can be connect'ed to for
+      # stream operation.
+      s.connect(usocket.getaddrinfo('www.micropython.org', 80, 0, SOCK_STREAM)[0][-1])
+
    .. admonition:: Difference to CPython
       :class: attention