doh: clarify warning about legacy DoH in docs

diff --git a/doc/upgrading.rst b/doc/upgrading.rst
index 76c5d56bbac7a9e91818dc6a294fdab05a514892..13a19693bccc2a4bbcab7123bf60a13618cde68a 100644 (file)
--- a/doc/upgrading.rst
+++ b/doc/upgrading.rst
@@ -18,15 +18,12 @@ Following section provides information about selected changes in not-yet-release
 We advise users to prepare for these changes sooner rather than later to make it easier to upgrade to
 newer versions when they are released.
 
-* Human readable output from :ref:`control-sockets` is not stable and changes from time to time.
-  Users who need machine readable output for scripts should use Lua function
-  ``tojson()`` to convert Lua values into standard JSON format instead of attempting to parse
-  the human readable output. For example API call ``tojson(cache.stats())\n`` will return JSON string
-  with ``cache.stats()`` results represented as dictionary.
-  Function ``tojson()`` is available in all resolver versions >= 1.0.0.
-* DoH served with http module :ref:`DNS-over-HTTP (DoH) <mod-http-doh>` will be marked as legacy
-  and won't receive any more bugfixes. A more reliable and scalable DoH module will be available
-  instead. The new DoH module will only support HTTP/2 over TLS.
+* Going forward DNS-over-HTTP (DoH) will be supported only over HTTP/2 with TLS.
+  This limitation allows us to provide a new :ref:`more reliable and scalable implementation
+  of DoH <dns-over-https>` (``kind='doh2'``).
+* DoH over HTTP/1 and unencrypted transports is still available in
+  :ref:`legacy http module <mod-http-doh>` (``kind='doh'``).
+  This module will not receive receive any more bugfixes and will be eventually removed.
 * New releases since October 2020 will contain changes for
   `DNS Flag Day 2020 <https://dnsflagday.net/2020/>`_. Please double-check your firewall,
   it has to allow DNS traffic on UDP and also TCP port 53.

diff --git a/modules/http/README.rst b/modules/http/README.rst
index b02b00abf1b8ab0564f753877b3d879303aac5ea..e2d1b991cdc87e66174c0b12b4f4abe1ebcfa564 100644 (file)
--- a/modules/http/README.rst
+++ b/modules/http/README.rst
@@ -129,9 +129,9 @@ Major drawback is that current browsers won't do HTTP/2 over insecure connection
 Legacy DNS-over-HTTPS (DoH)
 ---------------------------
 
-.. warning:: The DoH implementation using ``http`` module is deprecated. It has
-   known performance and stability issues that won't be fixed. Use
-   :ref:`dns-over-https` instead.
+.. warning:: The legacy DoH implementation using ``http`` module (``kind='doh'``)
+   is deprecated. It has known performance and stability issues that won't be fixed.
+   Use new :ref:`dns-over-https` implementation instead.
 
 This was an experimental implementation of :rfc:`8484`. It was configured using
 ``doh`` kind in :func:`net.listen`. Its configuration (such as certificates)