From fdc0d6924dbc5e5ef4c31f7128ab1c44aae6d903 Mon Sep 17 00:00:00 2001
From: Miek Gieben <miek@miek.nl>
Date: Sat, 5 May 2012 20:47:23 +0200
Subject: [PATCH] Documentation

---
 client.go | 24 +++++++++++++++---------
 dns.go    | 15 ++++++++-------
 2 files changed, 23 insertions(+), 16 deletions(-)

diff --git a/client.go b/client.go
index 3f160509..1ba3c05f 100644
--- a/client.go
+++ b/client.go
@@ -1,11 +1,6 @@
 package dns
 
 // A concurrent client implementation. 
-// Client sends query to a channel which
-// will then handle the query. Returned replys
-// are return on another channel. Ready for handling --- same
-// setup for server - a HANDLER function that gets run
-// when the query returns.
 
 import (
 	"io"
@@ -13,7 +8,6 @@ import (
 	"time"
 )
 
-// Incoming (documentation just as in os.Signal)
 type QueryHandler interface {
 	QueryDNS(w RequestWriter, q *Msg)
 }
@@ -88,7 +82,7 @@ var (
 // QueryHandler object that calls f.
 type HandlerQueryFunc func(RequestWriter, *Msg)
 
-// QueryDNS calls f(w, reg)
+// QueryDNS calls f(w, reg).
 func (f HandlerQueryFunc) QueryDNS(w RequestWriter, r *Msg) {
 	go f(w, r)
 }
@@ -229,7 +223,13 @@ func (w *reply) Write(m *Msg) error {
 }
 
 // Do performs an asynchronous query. The result is returned on the
-// QueryChan channel set in the Client c. 
+// QueryChan channel set in the *Client c. Basic use pattern for
+// sending message m to the server listening on port 53 on localhost
+//
+// c.Do(m, "127.0.0.1:53")		// Sends to c.QueryChan
+// r := <- DefaultReplyChan		// The reply comes back on DefaultReplyChan
+// 
+// r is of type Exchange.
 func (c *Client) Do(m *Msg, a string) {
 	c.QueryChan <- &Request{Client: c, Addr: a, Request: m}
 }
@@ -261,7 +261,13 @@ func (c *Client) exchangeBuffer(inbuf []byte, a string, outbuf []byte) (n int, w
 }
 
 // Exchange performs an synchronous query. It sends the message m to the address
-// contained in a and waits for an reply.
+// contained in a and waits for an reply. Basic use pattern with a *Client:
+//
+//	c := NewClient()
+//	in, rtt, addr, err := c.Exchange(m1, "127.0.0.1:53")
+// 
+// The 'addr' return value is superfluous in this case, but it is here to retain symmetry
+// with the asynchronous call, see Client.Do().
 func (c *Client) Exchange(m *Msg, a string) (r *Msg, rtt time.Duration, addr net.Addr, err error) {
 	var n int
 	var w *reply
diff --git a/dns.go b/dns.go
index da53015c..8c8f74d5 100644
--- a/dns.go
+++ b/dns.go
@@ -66,11 +66,12 @@
 //      c.Do(m1, "127.0.0.1:53")
 //      // Do something else
 //      r := <- DefaultReplyChan
-//      // r.Reply is the answer
-//      // r.Request is the original request
-//	// r.Rtt is the round trip time
-//	// r.RemoteAddr is the net.Addr were the request was sent to
-//      // r.Error is the error (if any)
+//      // r is of type Exchange:
+//      // * r.Reply is the answer
+//      // * r.Request is the original request
+//      // * r.Rtt is the round trip time
+//      // * r.RemoteAddr is the net.Addr were the request was sent to
+//      // * r.Error is the error (if any)
 package dns
 
 import (
@@ -121,8 +122,8 @@ type RR interface {
 type Exchange struct {
 	Request    *Msg          // the question sent
 	Reply      *Msg          // the answer to the question that was sent
-	Rtt        time.Duration // Round trip time
-	RemoteAddr net.Addr      // Client address
+	Rtt        time.Duration // round trip time
+	RemoteAddr net.Addr      // client address
 	Error      error         // if something went wrong, this contains the error
 }