From: Otto <otto.moerbeek@open-xchange.com>
Date: Wed, 10 Feb 2021 13:55:54 +0000 (+0100)
Subject: Take the DNSName docs from auth, they are more complete.
X-Git-Tag: dnsdist-1.6.0-alpha2~44^2
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=refs%2Fpull%2F10076%2Fhead;p=thirdparty%2Fpdns.git

Take the DNSName docs from auth, they are more complete.

We really should be having one source for all common Lua docs.
Fixes #9608.
---

diff --git a/pdns/recursordist/docs/lua-scripting/dnsname.rst b/pdns/recursordist/docs/lua-scripting/dnsname.rst
index 0014afe8ff..909e5e1506 100644
--- a/pdns/recursordist/docs/lua-scripting/dnsname.rst
+++ b/pdns/recursordist/docs/lua-scripting/dnsname.rst
@@ -28,6 +28,9 @@ A small example of the functionality of a :class:`DNSName` is shown below:
     print('it is')
   end
 
+Functions and methods of a ``DNSName``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 .. function:: newDN(name) -> DNSName
 
   Returns the :class:`DNSName` object of ``name``.
@@ -37,44 +40,71 @@ A small example of the functionality of a :class:`DNSName` is shown below:
 .. class:: DNSName
 
   A ``DNSName`` object represents a name in the DNS.
+  It is returned by several functions and has several functions to programmatically interact with it.
 
-  .. method:: DNSName:chopOff() -> bool
+  .. method:: DNSName:canonCompare(name) -> bool
 
-    Removes the left-most label and returns ``true``.
-    ``false`` is returned if no label was removed
+    Performs a comparison of DNS names in canonical order.
+    Returns true if the DNSName comes before ``name``.
+    See https://tools.ietf.org/html/rfc4034#section-6
 
-  .. method:: DNSName:countLabels() -> int
+    :param DNSName name: The name to compare to
 
-    Returns the number of DNSLabels in the name
+  .. method:: DNSName:makeRelative(name) -> DNSName
+
+    Returns a new DNSName that is relative to ``name``
 
-  .. method:: DNSName:equal(name) -> bool
+    .. code-block:: lua
 
-    Returns true when both names are equal for the DNS, i.e case insensitive.
-    
-    To compare two ``DNSName`` objects, use ``==``.
+      name = newDN("bb.a.example.com.")
+      parent = newDN("example.com.")
+      rel = name:makeRelative(parent) -- contains DNSName("bb.a.")
 
-    :param DNSName string: The name to compare against.
+    :param DNSName name: The name to compare to
 
   .. method:: DNSName:isPartOf(name) -> bool
 
     Returns true if the DNSName is part of the DNS tree of ``name``.
 
-    .. code-block:: Lua
+    :param DNSName name: The name to check against
 
-      newDN("www.powerdns.com"):isPartOf(newDN("CoM.")) -- true
+  .. method:: DNSName:toString() -> string
 
-    :param DNSName name: The name to check against
+    Returns a human-readable form of the DNSName
+
+  .. method:: DNSName:toStringNoDot() -> string
 
-  .. method:: DNSName:toString() -> str
-              DNSName:toStringNoDot() -> str
+    Returns a human-readable form of the DNSName without the trailing dot
 
-    Returns a human-readable form of the DNSName.
-    With or without trailing dot.
+  .. method:: DNSName:chopOff() -> bool
 
-  .. method:: DNSName:wirelength() -> int
+    Removes the left-most label and returns ``true``.
+    ``false`` is returned if no label was removed
+
+  .. method:: DNSName:countLabels() -> int
+
+    Returns the number of DNSLabels in the name
+
+  .. method:: DNSName:wireLength() -> int
 
     Returns the length in bytes of the DNSName as it would be on the wire.
 
+  .. method:: DNSName::getRawLabels() -> [ string ]
+
+    Returns a table that contains the raw labels of the DNSName
+
+  .. method:: DNSName::countLabels() -> int
+
+    Returns the number of labels of the DNSName
+
+  .. method:: DNSName::equal(name) -> bool
+
+    Perform a comparison of the DNSName to the given ``name``.
+    You can also compare directly two DNSName objects using
+    the ``==`` operator
+
+    :param string name: The name to compare to
+
 DNS Suffix Match Groups
 -----------------------