From 1c1a7477dc962000571dbcdbc80fd2390a67067f Mon Sep 17 00:00:00 2001
From: Daniele Varrazzo <daniele.varrazzo@gmail.com>
Date: Tue, 26 Jul 2022 13:58:53 +0100
Subject: [PATCH] docs: mention 3.1 automatic DNS resolution in async page

Also fix several glitches in the dns page documentation.
---
 docs/advanced/async.rst | 17 ++++++++++-------
 docs/api/dns.rst        | 16 ++++++++++------
 2 files changed, 20 insertions(+), 13 deletions(-)

diff --git a/docs/advanced/async.rst b/docs/advanced/async.rst
index bbcfbd042..409a094e6 100644
--- a/docs/advanced/async.rst
+++ b/docs/advanced/async.rst
@@ -28,17 +28,20 @@ here and there.
             async for record in acur:
                 print(record)
 
+.. versionchanged:: 3.1
 
-.. warning::
+    `AsyncConnection.connect()` performs DNS name resolution in a non-blocking
+    way.
 
-    `AsyncConnection.connect()` may still block on DNS name resolution.
-    To avoid that you should `set the hostaddr connection parameter`__.
+    .. warning::
 
-    The `~psycopg._dns.resolve_hostaddr_async()` is an experimental solution
-    to help to do that. Feedback about the feature is welcome!
+        Before version 3.1, `AsyncConnection.connect()` may still block on DNS
+        name resolution. To avoid that you should `set the hostaddr connection
+        parameter`__, or use the `~psycopg._dns.resolve_hostaddr_async()` to
+        do it automatically.
 
-    .. __: https://www.postgresql.org/docs/current/libpq-connect.html
-           #LIBPQ-PARAMKEYWORDS
+        .. __: https://www.postgresql.org/docs/current/libpq-connect.html
+               #LIBPQ-PARAMKEYWORDS
 
 .. warning::
 
diff --git a/docs/api/dns.rst b/docs/api/dns.rst
index d12de3ae2..186bde39a 100644
--- a/docs/api/dns.rst
+++ b/docs/api/dns.rst
@@ -23,12 +23,13 @@ server before performing a connection.
     .. _dnspython: https://dnspython.readthedocs.io/
 
 
-.. function:: resolve_srv
+.. function:: resolve_srv(params)
 
     Apply SRV DNS lookup as defined in :RFC:`2782`.
 
     :param params: The input parameters, for instance as returned by
         `~psycopg.conninfo.conninfo_to_dict()`.
+    :type params: `!dict`
     :return: An updated list of connection parameters.
 
     For every host defined in the ``params["host"]`` list (comma-separated),
@@ -43,10 +44,10 @@ server before performing a connection.
     perform SRV lookup also if the the port is the string ``SRV`` (case
     insensitive).
 
-   .. warning::
+    .. warning::
        This is an experimental functionality.
 
-   .. note::
+    .. note::
        One possible way to use this function automatically is to subclass
        `~psycopg.Connection`, extending the
        `~psycopg.Connection._get_connection_params()` method::
@@ -64,7 +65,8 @@ server before performing a connection.
            cnn = SrvCognizantConnection.connect("host=_postgres._tcp.db.psycopg.org")
 
 
-.. function:: resolve_srv_async
+.. function:: resolve_srv_async(params)
+    :async:
 
     Async equivalent of `resolve_srv()`.
 
@@ -91,7 +93,8 @@ server before performing a connection.
        This is an experimental method.
 
 
-.. function:: resolve_hostaddr_async
+.. function:: resolve_hostaddr_async(params)
+    :async:
 
     Perform async DNS lookup of the hosts and return a new params dict.
 
@@ -102,6 +105,7 @@ server before performing a connection.
 
     :param params: The input parameters, for instance as returned by
         `~psycopg.conninfo.conninfo_to_dict()`.
+    :type params: `!dict`
 
     If a ``host`` param is present but not ``hostname``, resolve the host
     addresses dynamically.
@@ -122,7 +126,7 @@ server before performing a connection.
     .. warning::
         Before psycopg 3.1, this function doesn't handle the ``/etc/hosts`` file.
 
-   .. note::
+    .. note::
        Starting from psycopg 3.1, a similar operation is performed
        automatically by `!AsyncConnection._get_connection_params()`, so this
        function is unneeded.
-- 
2.47.2