bin/djbdns-logparse.py: add docs/examples for handle_tinydns_log().

diff --git a/bin/djbdns-logparse.py b/bin/djbdns-logparse.py
index 3a25a5a52bf4dceb4e5376c4644abf12a361918d..ed8538174e6b232773d5a64ddc38eec58cf278a7 100755 (executable)
--- a/bin/djbdns-logparse.py
+++ b/bin/djbdns-logparse.py
@@ -176,11 +176,37 @@ def handle_dnscache_log(line, match):
     print(timestamp, event, " ".join(words))
 
 
-def handle_tinydns_log(line, match):
+def handle_tinydns_log(line : str, match: re.Match):
+    """
+    Handle a line that matched the ``tinydns_log_re`` regex.
+
+    Parameters
+    ----------
+
+    line : string
+        The tinydns log line that matched ``tinydns_log_re``.
+
+    match : re.Match
+        The match object that was returned when ``line`` was
+        tested against ``tinydns_log_re``.
+
+    Examples
+    --------
+
+        >>> line = "2022-09-14 21:04:40.206516500 7f000001:9d61:be69 - 0001 www.example.com"
+        >>> match = tinydns_log_re.match(line)
+        >>> handle_tinydns_log(line, match)
+        2022-09-14 21:04:40.206516500 dropped query (no authority) from 127.0.0.1:40289 (id 48745): a www.example.com
+
+    """
     (timestamp, ip, port, id, code, type, name) = match.groups()
     ip = convert_ip(ip)
     port = int(port, 16)
     id = int(id, 16)
+
+    # Convert the "type" field to a human-readable record type name
+    # using the query_type dictionary. If the right name isn't present
+    # in the dictionary, we use the (decimal) type id instead.
     type = int(type, 16)                # "001c" -> 28
     type = query_type.get(type, type)   # 28 -> "aaaa"