hints docs: unify the descriptions of `hints.root()`

(Thanks to Láďa.)
Also try to stress that hints.set() only takes a pair and not more.

diff --git a/modules/hints/README.rst b/modules/hints/README.rst
index c28f5683873b8769edf25b98005fbb9d687e62a4..91424396fae39fa7c04aa6c3935505e400ccf79a 100644 (file)
--- a/modules/hints/README.rst
+++ b/modules/hints/README.rst
@@ -58,11 +58,12 @@ Properties
   :param string pair:  ``hostname address`` i.e. ``"localhost 127.0.0.1"``
   :return: ``{ result: bool }``
 
-  Add a hostname - address pair hint.
+  Add a hostname--address pair hint.
 
   .. note::
 
-    If multiple addresses have been added for a name, all are returned in a forward query.
+    If multiple addresses have been added for a name (in separate ``hints.set()`` commands),
+    all are returned in a forward query.
     If multiple names have been added to an address, the last one defined is returned
     in a corresponding PTR query.
 
@@ -73,12 +74,6 @@ Properties
 
   Remove a hostname - address pair hint.  If address is omitted, all addresses for the given name are deleted.
 
-.. function:: hints.root()
-
-  :return: ``{ ['a.root-servers.net.'] = { '1.2.3.4', '5.6.7.8', ...}, ... }``
-
-  .. tip:: If no parameters are passed, returns current root hints set.
-
 .. function:: hints.root_file(path)
 
   Replace current root hints from a zonefile.  If the path is omitted, the compiled-in path is used, i.e. the root hints are reset to the default.
@@ -90,6 +85,8 @@ Properties
 
   Replace current root hints and return the current table of root hints.
 
+  .. tip:: If no parameters are passed, it only returns current root hints set without changing anything.
+
   Example:
 
   .. code-block:: lua