From 539ffadba76f2ebf3741dfa14ad21c53a29dbac3 Mon Sep 17 00:00:00 2001
From: Armon Dadgar <armon.dadgar@gmail.com>
Date: Fri, 7 Mar 2014 16:50:31 -0800
Subject: [PATCH] Improve documentation

---
 README.md   | 21 +++++++++++++++++++++
 protocol.go | 10 ++++++++++
 2 files changed, 31 insertions(+)

diff --git a/README.md b/README.md
index 113423c..25a779c 100644
--- a/README.md
+++ b/README.md
@@ -8,8 +8,29 @@ instead of the load balancer.
 
 This library provides both a net.Listener and net.Conn implementation that
 can be used to handle situation in which you may be using the proxy protocol.
+Only proxy protocol version 1, the human-readable form, is understood.
 
 The only caveat is that we check for the "PROXY " prefix to determine if the protocol
 is being used. If that string may occur as part of your input, then it is ambiguous
 if the protocol is being used and you may have problems.
 
+# Documentation
+
+Full documentation can be found [here](http://godoc.org/github.com/armon/go-proxyproto).
+
+# Examples
+
+Using the library is very simple:
+
+```
+
+// Create a listener
+list, err := net.Listen("tcp", "...")
+
+// Wrap listener in a proxyproto listener
+proxyList := &proxyproto.Listener{list}
+conn, err :=proxyList.Accept()
+
+...
+```
+
diff --git a/protocol.go b/protocol.go
index 5175cd6..9585447 100644
--- a/protocol.go
+++ b/protocol.go
@@ -68,6 +68,9 @@ func NewConn(conn net.Conn) *Conn {
 	return pConn
 }
 
+// Read is check for the proxy protocol header when doing
+// the initial scan. If there is an error parsing the header,
+// it is returned and the socket is closed.
 func (p *Conn) Read(b []byte) (int, error) {
 	var err error
 	p.once.Do(func() { err = p.checkPrefix() })
@@ -89,6 +92,13 @@ func (p *Conn) LocalAddr() net.Addr {
 	return p.conn.LocalAddr()
 }
 
+// RemoteAddr returns the address of the client if the proxy
+// protocol is being used, otherwise just returns the address of
+// the socket peer. If there is an error parsing the header, the
+// address of the client is not returned, and the socket is closed.
+// Once implication of this is that the call could block if the
+// client is slow. Using a Deadline is recommended if this is called
+// before Read()
 func (p *Conn) RemoteAddr() net.Addr {
 	p.once.Do(func() {
 		if err := p.checkPrefix(); err != nil {