Improve documentation

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()
+
+...
+```
+

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 {