Add missing docstrings and examples

src/ddns_service/dns.py

@@ -37,6 +37,12 @@ def encode_dnsname(hostname):
 
     Raises:
         EncodingError: If hostname is invalid.
+
+    Example:
+        >>> encode_dnsname("münchen")
+        'xn--mnchen-3ya'
+        >>> encode_dnsname("example.com.")
+        'example.com'
     """
     hostname = hostname.lower().strip()
 
@@ -84,6 +90,24 @@ def encode_dnsname(hostname):
 
 
 def detect_ip_type(ip):
+    """
+    Detect IP address type and normalize.
+
+    Args:
+        ip: IP address string.
+
+    Returns:
+        Tuple of (record_type, normalized_ip).
+
+    Raises:
+        ValueError: If IP address is invalid.
+
+    Example:
+        >>> detect_ip_type("192.168.1.1")
+        ('A', '192.168.1.1')
+        >>> detect_ip_type("2001:db8::1")
+        ('AAAA', '2001:db8::1')
+    """
     try:
         addr = ipaddress.ip_address(ip)
         if isinstance(addr, ipaddress.IPv4Address):
@@ -127,6 +151,16 @@ def parse_bind_key_file(path):
 
     Raises:
         DNSError: If parsing fails.
+
+    Example:
+        Key file contents::
+
+            key "ddns-key." {
+                algorithm hmac-sha256;
+                secret "base64secret==";
+            };
+
+        >>> keyring, algo = parse_bind_key_file("/etc/bind/ddns.key")
     """
     if not path:
         return None, None
@@ -324,13 +358,17 @@ class DNSService:
         Update a DNS record for the given hostname.
 
         Args:
-            hostname: Fully qualified hostname.
+            hostname: Hostname (without zone suffix).
             zone: DNS zone name.
             ip: IP address to set.
             ttl: DNS record TTL.
 
         Raises:
             DNSError: If update fails.
+
+        Example:
+            >>> dns_service.update_record("myhost", "example.com", "192.168.1.1", 60)
+            >>> dns_service.update_record("myhost", "example.com", "2001:db8::1", 60)
         """
         try:
             record_type, normalized_ip = detect_ip_type(ip)