doc: document options

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,