Merge pull request #66 from libp2p/fix/docs-and-nits

docs and nits

notify.go

@@ -13,7 +13,7 @@ var _ inet.Notifiee = (*RelayNotifiee)(nil)
 
 type RelayNotifiee Relay
 
-func (r *Relay) Notifiee() inet.Notifiee {
+func (r *Relay) notifiee() inet.Notifiee {
 	return (*RelayNotifiee)(r)
 }
 

relay.go

@@ -27,6 +27,7 @@ const maxMessageSize = 4096
 var RelayAcceptTimeout = time.Minute
 var HopConnectTimeout = 10 * time.Second
 
+// Relay is the relay transport and service.
 type Relay struct {
 	host     host.Host
 	upgrader *tptu.Upgrader
@@ -47,11 +48,22 @@ type Relay struct {
 	lhLk     sync.Mutex
 }
 
+// RelayOpts are options for configuring the relay transport.
 type RelayOpt int
 
 var (
-	OptActive    = RelayOpt(0)
-	OptHop       = RelayOpt(1)
+	// OptActive configures the relay transport to actively establish
+	// outbound connections on behalf of clients. You probably don't want to
+	// enable this unless you know what you're doing.
+	OptActive = RelayOpt(0)
+	// OptHop configures the relay transport to accept requests to relay
+	// traffic on behalf of third-parties. Unless OptActive is specified,
+	// this will only relay traffic between peers already connected to this
+	// node.
+	OptHop = RelayOpt(1)
+	// OptDiscovery configures this relay transport to discover new relays
+	// by probing every new peer. You almost _certainly_ don't want to
+	// enable this.
 	OptDiscovery = RelayOpt(2)
 )
 
@@ -63,6 +75,7 @@ func (e RelayError) Error() string {
 	return fmt.Sprintf("error opening relay circuit: %s (%d)", pb.CircuitRelay_Status_name[int32(e.Code)], e.Code)
 }
 
+// NewRelay constructs a new relay.
 func NewRelay(ctx context.Context, h host.Host, upgrader *tptu.Upgrader, opts ...RelayOpt) (*Relay, error) {
 	r := &Relay{
 		upgrader: upgrader,
@@ -90,7 +103,7 @@ func NewRelay(ctx context.Context, h host.Host, upgrader *tptu.Upgrader, opts ..
 	h.SetStreamHandler(ProtoID, r.handleNewStream)
 
 	if r.discovery {
-		h.Network().Notify(r.Notifiee())
+		h.Network().Notify(r.notifiee())
 	}
 
 	return r, nil