Updating usage docs for relay/autorelay

p2p/host/relay/autorelay.go

@@ -56,6 +56,10 @@ type AutoRelayHost struct {
 	addrs  []ma.Multiaddr
 }
 
+// Warning:  This function should not be used directly by clients activating
+// autorelay. NewAutoRelayHost is used internally by the libp2p.New generator.
+// To enable autorelay, use the EnableAutoRelay Option.
+// https://godoc.org/github.com/libp2p/go-libp2p#EnableAutoRelay
 func NewAutoRelayHost(ctx context.Context, bhost *basic.BasicHost, discover discovery.Discoverer, router routing.PeerRouting) *AutoRelayHost {
 	h := &AutoRelayHost{
 		BasicHost:  bhost,

p2p/host/relay/doc.go

@@ -6,21 +6,22 @@ feature is dubbed `autorelay`.
 Warning: the internal interfaces are unstable.
 
 System Components:
-- AutoNATService instances -- see https://github.com/libp2p/go-libp2p-autonat-svc
-- One or more relays, instances of `RelayHost`
-- The autorelayed hosts, instances of `AutoRelayHost`.
+  - AutoNATService instances -- see https://github.com/libp2p/go-libp2p-autonat-svc
+  - One or more relays, instances of `RelayHost`
+  - The autorelayed hosts, instances of `AutoRelayHost`.
 
 How it works:
-- `AutoNATService` instances are instantiated in the
+
+- AutoNATService
+  `AutoNATService` instances are instantiated in the
   bootstrappers (or other well known publicly reachable hosts)
 
-- `RelayHost`s are constructed with
-  `libp2p.New(libp2p.EnableRelay(circuit.OptHop), libp2p.Routing(makeDHT))`.
-  They provide Relay Hop services, and advertise through the DHT
+- RelayHost
+  RelayHosts provide Relay Hop services, and advertise through the DHT
   in the `/libp2p/relay` namespace
 
-- `AutoRelayHost`s are constructed with `libp2p.New(libp2p.Routing(makeDHT))`
-  They passively discover autonat service instances and test dialability of
+- AutoRelayHost
+  AutoRelayHosts passively discover autonat service instances and test dialability of
   their listen address set through them.  When the presence of NAT is detected,
   they discover relays through the DHT, connect to some of them and begin
   advertising relay addresses.  The new set of addresses is propagated to

p2p/host/relay/examples_test.go

@@ -0,0 +1,34 @@
+package relay_test
+
+import (
+	"context"
+	"github.com/libp2p/go-libp2p-circuit"
+
+	libp2p "github.com/libp2p/go-libp2p"
+
+	host "github.com/libp2p/go-libp2p-host"
+	routing "github.com/libp2p/go-libp2p-routing"
+)
+
+func ExampleNewRelayHost() {
+	ctx := context.Background()
+	var relayOpts []relay.RelayOpt
+
+	libp2p.New(ctx, libp2p.EnableRelay(relayOpts...))
+}
+
+func ExampleNewAutoRelayHost() {
+	ctx := context.Background()
+	var relayOpts []relay.RelayOpt
+
+	// In a non-example use case `makeRouting` will need to return an instance of
+	// the DHT, using https://godoc.org/github.com/libp2p/go-libp2p-kad-dht#New
+	makeRouting := func(h host.Host) (routing.PeerRouting, error) {
+		mtab := newMockRoutingTable()
+		mr := newMockRouting(h, mtab)
+		return mr, nil
+	}
+
+	opts := []libp2p.Option{libp2p.EnableRelay(relayOpts...), libp2p.EnableAutoRelay(), libp2p.Routing(makeRouting)}
+	libp2p.New(ctx, opts...)
+}

p2p/host/relay/relay.go

@@ -22,7 +22,9 @@ type RelayHost struct {
 	addrsF    basic.AddrsFactory
 }
 
-// New constructs a new RelayHost
+// Warning:  This function should not be used directly by clients activating
+// relay. NewRelayHost is used internally by the libp2p.New generator. To enable
+// relay, use the EnableRelay Option. https://godoc.org/github.com/libp2p/go-libp2p#EnableRelay
 func NewRelayHost(ctx context.Context, bhost *basic.BasicHost, advertise discovery.Advertiser) *RelayHost {
 	h := &RelayHost{
 		BasicHost: bhost,