Fix documentation

TODO

@@ -7,6 +7,7 @@ Todo:
 * NSEC and nsec3 closest encloser helper functions
 * Tsig generation for replies (request MAC)
 * pack/Unpack smaller. EDNS 'n stuff can be folded in
+* try to use net.Conn in server.go
 
 Longer term:
 * Parsing from strings, going with goyacc and own lexer

resolver.go

@@ -3,25 +3,7 @@
 // license that can be found in the LICENSE file.
 
 // DNS resolver client: see RFC 1035.
-// A DNS resolver is to be run in a goroutine. 
-// For every reply the resolver answers by sending the
-// received packet (with a possible error) back on a channel.
-// 
-// Basic usage pattern for setting up a resolver:
-//
-//        res := new(Resolver)
-//        ch := res.NewQuerier()                        // start new resolver
-//        res.Servers = []string{"127.0.0.1"}           // set the nameserver
-//
-//        m := new(Msg)                                 // prepare a new message
-//        m.MsgHdr.Recursion_desired = true             // header bits
-//        m.Question = make([]Question, 1)              // 1 RR in question sec.
-//        m.Question[0] = Question{"miek.nl", TypeSOA, ClassINET}
-//        ch <- Msg{m, nil, nil}                        // send the query
-//        in := <-ch                                    // wait for reply
-//
-// Note that message id checking is left to the caller.
-//
+
 package dns
 
 import (
@@ -45,8 +27,18 @@ type Resolver struct {
 	// rtt map[string]int server->int, smaller is faster 0, -1 is unreacheble
 }
 
-// Send a query using *res, q holds the question to be asked.
-// A new dns message with the answer is return and a possible error
+// Basic usage pattern for setting up a resolver:
+//
+//        res := new(Resolver)
+//        res.Servers = []string{"127.0.0.1"}           // set the nameserver
+//
+//        m := new(Msg)                                 // prepare a new message
+//        m.MsgHdr.Recursion_desired = true             // header bits
+//        m.Question = make([]Question, 1)              // 1 RR in question section
+//        m.Question[0] = Question{"miek.nl", TypeSOA, ClassINET}
+//        in, err := res.Query(m)                       // Ask the question
+//
+// Note that message id checking is left to the caller.
 func (res *Resolver) Query(q *Msg) (d *Msg, err os.Error) {
 	var (
 		c    net.Conn
@@ -102,8 +94,10 @@ func (res *Resolver) Query(q *Msg) (d *Msg, err os.Error) {
 	return in, nil
 }
 
-// q holds the inital query 
-// channel is closed by AXfr
+// Start an AXFR, q should contain a message with the question
+// for an AXFR ("miek.nl" ANY AXFR. All incoming axfr snippets
+// are returned on the channel m. The function closes the 
+// channel to signal the end of the AXFR.
 func (res *Resolver) Axfr(q *Msg, m chan *Msg) {
 	var port string
 	var err os.Error
@@ -176,7 +170,7 @@ SERVER:
 				}
 			}
 		}
-		println("Should never be reached")
+		panic("not reached")
 		return
 	}
 	close(m)
@@ -184,7 +178,8 @@ SERVER:
 }
 
 // Send a request on the connection and hope for a reply.
-// Up to res.Attempts attempts.
+// Up to res.Attempts attempts. If send is false, nothing
+// is send.
 func exchangeUDP(c net.Conn, m []byte, r *Resolver, send bool) (*Msg, os.Error) {
 	var timeout int64
 	var attempts int

server.go

@@ -4,22 +4,6 @@
 
 // DNS server implementation
 
-// Package responder implements a DNS server. Any nameserver needs to implement
-// the Responder interface to get things going. Each incoming query is handled
-// in a seperate goroutine.
-// 
-// Typical usage of the package:
-//
-//         type myserv Server
-//         func (s *myserv) ResponderUDP(c *net.UDPConn, a net.Addr, in []byte) { /* UDP reply */ }
-//         func (s *myserv) ResponderTCP(c *net.TCPConn, in []byte) { /* TCP reply */}
-//
-//         s := new(Server)             // create new sever
-//         s.Address = "127.0.0.1"      // listen address
-//         s.Port = "8053"              // listen port
-//         var m *myserv                       
-//         ch :=make(chan bool)
-//         go s.NewResponder(m, ch)     // start the responder
 package dns
 
 import (
@@ -132,7 +116,25 @@ func accepterTCP(l *net.TCPListener, ch chan *Request, quit chan bool) {
 	panic("not reached")
 }
 
-// Setup both the udp and tcp listener
+// This function implements a nameserver. It should be run as a goroutines.
+// The function itself starts two new goroutines (one for TCP and one for UDP)
+// and for each incoming message run the ReplyTCP or ReplyUCP again as a 
+// goroutine.
+// 
+// Typical usage of ListenAndServe:
+//
+//         type myserv dns.Server
+//         func (s *myserv) ReplyUDP(c *net.UDPConn, a net.Addr, in []byte) { 
+//              /* UDP reply */ 
+//         }
+//         func (s *myserv) ReplyTCP(c *net.TCPConn, a net.Addr, in []byte) {
+//              /* TCP reply */
+//         }
+//
+//         var m *myserv                       
+//         ch := make(chan bool)
+//         go dns.ListenAndServe("127.0.0.1:8053", m, ch)
+//         m <- true                    // stop the goroutine
 func ListenAndServe(addr string, handler Handler, q chan bool) os.Error {
 	ta, err := net.ResolveTCPAddr(addr)
 	if err != nil {