added more documentation

scheme/lib/dns.scm

@@ -11,25 +11,55 @@
 ;       - types from newer RFCs (41, unknown)
 ;       - more documentation
 ;
+; ---
+; sample usage & documentation:
 ;
-; sample usage:
+;  <name>, <ip-string> and <nameserver> are strings.
 ;
-;  (dns-lookup-name <name> [nameserver]) --> <ip>
+;  <nameserver> can either be a domainname or a ip.
-;  (dns-lookup-ip <ip> [nameserver]) --> <name>
+;  if it is a domainname, its ip is looked up on a nameserver listed in
-;  (dns-lookup-nameserver <name> [nameserver]) --> <list of ips of authoritative nameservers>
+;  /etc/resolv.conf.
-;  (dns-lookup-mail-exchanger <name> [nameserver]) --> <list of names of mail-exchangers>
+;
+;  (dns-find-nameserver) --> <ip-string>
+;  this parses the /etc/resolv.conf file and returns the first found 
+;  nameserver.
+;
+;
+;  
+;  (dns-lookup-name <name> [nameserver]) --> <ip-string>
+;  (dns-lookup-ip <ip-string> [nameserver]) --> <name>
+;  (dns-lookup-nameserver <name> [nameserver]) 
+;                        --> <list of ip-strings of authoritative nameservers>
+;  (dns-lookup-mail-exchanger <name> [nameserver]) 
+;                        --> <list of names of mail-exchangers>
+; 
+;  dns-lookup-name, dns-lookup-ip, dns-lookup-nameserver and 
+;  dns-lookup-mail-exchanger are "simple lookup functions",
+;  they return the wanted information or #f.
 ;   
-;  (dns-lookup <name/ip> <type> [nameserver]) --> <dns-message>
+;
+;  (dns-lookup <name/ip-string> <type> [nameserver]) --> <dns-message>
 ;  (show-dns-message <dns-message) --> the whole message, human readable
 ;
-;  (concurrent-lookup <dns-lookup-*> <name>)
+;  a <dns-message> is a record, with several entries, which holds the whole
+;  query/response dialog. the simplest way to get detailed information about
+;  the record structure is to view the result of show-dns-message.
+;
+;  dns-lookup returns much more information than the simple lookup functions, 
+;  only useful in very special cases.
+;  
+;
+;  (concurrent-lookup <simple lookup function> <name>)
+;  starts a concurrent lookup to all nameservers in /etc/resolv.conf.
+;  the simple lookup function defines the lookup type.
+;
 ;
 ;  some lookups return a hostname (e.g. mx). 
 ;  many applications need instead of a hostname a ip address.
 ;  force-ip and force-ip-list guarantee that a ip address is
 ;  returned.
 ;
-;  (force-ip <name>) --> <ip>
+;  (force-ip <name>) --> <ip-string>
 ;  (force-ip-list <list of names>) --> <list of ips>