From f2414b1a2949469b015cd937a58f7fcdb4a7a8f1 Mon Sep 17 00:00:00 2001
From: Mantas Vidutis <mantas.a.vidutis@gmail.com>
Date: Sun, 13 Jan 2019 18:53:10 -0800
Subject: [PATCH 1/4] updating usage docs for relay/autorelay

---
 p2p/host/relay/autorelay.go      |  4 ++++
 p2p/host/relay/autorelay_test.go | 13 +++++++++++++
 p2p/host/relay/doc.go            | 19 ++++++++++---------
 p2p/host/relay/relay.go          |  5 ++++-
 p2p/host/relay/relay_test.go     | 15 +++++++++++++++
 5 files changed, 46 insertions(+), 10 deletions(-)
 create mode 100644 p2p/host/relay/relay_test.go

diff --git a/p2p/host/relay/autorelay.go b/p2p/host/relay/autorelay.go
index d91f31eee1..6603b1a92d 100644
--- a/p2p/host/relay/autorelay.go
+++ b/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.config.NewNode
+// 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,
diff --git a/p2p/host/relay/autorelay_test.go b/p2p/host/relay/autorelay_test.go
index c7bbeba7dc..b6a10e9bc2 100644
--- a/p2p/host/relay/autorelay_test.go
+++ b/p2p/host/relay/autorelay_test.go
@@ -16,6 +16,7 @@ import (
 	autonatpb "github.com/libp2p/go-libp2p-autonat/pb"
 	circuit "github.com/libp2p/go-libp2p-circuit"
 	host "github.com/libp2p/go-libp2p-host"
+	dht "github.com/libp2p/go-libp2p-kad-dht"
 	inet "github.com/libp2p/go-libp2p-net"
 	peer "github.com/libp2p/go-libp2p-peer"
 	pstore "github.com/libp2p/go-libp2p-peerstore"
@@ -218,3 +219,15 @@ func TestAutoRelay(t *testing.T) {
 		t.Fatal("No relay addrs pushed")
 	}
 }
+
+// godoc examples
+
+func ExampleNewAutoRelayHost() {
+	ctx := context.Background()
+	makeRouting := func(h host.Host) (routing.PeerRouting, error) {
+		return dht.New(ctx, h)
+	}
+	opts := []libp2p.Option{libp2p.EnableRelay(), libp2p.EnableAutoRelay(), libp2p.Routing(makeRouting)}
+
+	libp2p.New(ctx, opts...)
+}
\ No newline at end of file
diff --git a/p2p/host/relay/doc.go b/p2p/host/relay/doc.go
index c0a5878113..96ffff5b18 100644
--- a/p2p/host/relay/doc.go
+++ b/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
diff --git a/p2p/host/relay/relay.go b/p2p/host/relay/relay.go
index b5db9ce586..8733173460 100644
--- a/p2p/host/relay/relay.go
+++ b/p2p/host/relay/relay.go
@@ -22,7 +22,10 @@ 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.config.NewNode
+// 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,
diff --git a/p2p/host/relay/relay_test.go b/p2p/host/relay/relay_test.go
new file mode 100644
index 0000000000..88d0ea9385
--- /dev/null
+++ b/p2p/host/relay/relay_test.go
@@ -0,0 +1,15 @@
+package relay
+
+import (
+	"context"
+
+	"github.com/libp2p/go-libp2p"
+)
+
+// godoc examples
+
+func ExampleNewRelayHost() {
+	ctx := context.Background()
+
+	libp2p.New(ctx, libp2p.EnableRelay())
+}
\ No newline at end of file

From 7a79d1453936d5f1042a1f89aff30c9a8d822f28 Mon Sep 17 00:00:00 2001
From: Mantas Vidutis <mantas.a.vidutis@gmail.com>
Date: Mon, 14 Jan 2019 08:46:08 -0800
Subject: [PATCH 2/4] no deps for usage examples

---
 p2p/host/relay/autorelay_test.go | 20 +++-----------------
 p2p/host/relay/examples_test.go  | 32 ++++++++++++++++++++++++++++++++
 p2p/host/relay/relay_test.go     | 15 ---------------
 3 files changed, 35 insertions(+), 32 deletions(-)
 create mode 100644 p2p/host/relay/examples_test.go
 delete mode 100644 p2p/host/relay/relay_test.go

diff --git a/p2p/host/relay/autorelay_test.go b/p2p/host/relay/autorelay_test.go
index b6a10e9bc2..66620ca5ed 100644
--- a/p2p/host/relay/autorelay_test.go
+++ b/p2p/host/relay/autorelay_test.go
@@ -1,4 +1,4 @@
-package relay_test
+package relay
 
 import (
 	"context"
@@ -8,7 +8,6 @@ import (
 	"time"
 
 	libp2p "github.com/libp2p/go-libp2p"
-	relay "github.com/libp2p/go-libp2p/p2p/host/relay"
 
 	ggio "github.com/gogo/protobuf/io"
 	cid "github.com/ipfs/go-cid"
@@ -16,7 +15,6 @@ import (
 	autonatpb "github.com/libp2p/go-libp2p-autonat/pb"
 	circuit "github.com/libp2p/go-libp2p-circuit"
 	host "github.com/libp2p/go-libp2p-host"
-	dht "github.com/libp2p/go-libp2p-kad-dht"
 	inet "github.com/libp2p/go-libp2p-net"
 	peer "github.com/libp2p/go-libp2p-peer"
 	pstore "github.com/libp2p/go-libp2p-peerstore"
@@ -29,8 +27,8 @@ import (
 func init() {
 	autonat.AutoNATIdentifyDelay = 500 * time.Millisecond
 	autonat.AutoNATBootDelay = 1 * time.Second
-	relay.BootDelay = 1 * time.Second
-	relay.AdvertiseBootDelay = 1 * time.Millisecond
+	BootDelay = 1 * time.Second
+	AdvertiseBootDelay = 1 * time.Millisecond
 	manet.Private4 = []*net.IPNet{}
 }
 
@@ -219,15 +217,3 @@ func TestAutoRelay(t *testing.T) {
 		t.Fatal("No relay addrs pushed")
 	}
 }
-
-// godoc examples
-
-func ExampleNewAutoRelayHost() {
-	ctx := context.Background()
-	makeRouting := func(h host.Host) (routing.PeerRouting, error) {
-		return dht.New(ctx, h)
-	}
-	opts := []libp2p.Option{libp2p.EnableRelay(), libp2p.EnableAutoRelay(), libp2p.Routing(makeRouting)}
-
-	libp2p.New(ctx, opts...)
-}
\ No newline at end of file
diff --git a/p2p/host/relay/examples_test.go b/p2p/host/relay/examples_test.go
new file mode 100644
index 0000000000..1309697189
--- /dev/null
+++ b/p2p/host/relay/examples_test.go
@@ -0,0 +1,32 @@
+package relay
+
+import (
+	"context"
+
+	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()
+
+	libp2p.New(ctx, libp2p.EnableRelay())
+}
+
+func ExampleNewAutoRelayHost() {
+	ctx := context.Background()
+
+	// 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(), libp2p.EnableAutoRelay(), libp2p.Routing(makeRouting)}
+
+	libp2p.New(ctx, opts...)
+}
\ No newline at end of file
diff --git a/p2p/host/relay/relay_test.go b/p2p/host/relay/relay_test.go
deleted file mode 100644
index 88d0ea9385..0000000000
--- a/p2p/host/relay/relay_test.go
+++ /dev/null
@@ -1,15 +0,0 @@
-package relay
-
-import (
-	"context"
-
-	"github.com/libp2p/go-libp2p"
-)
-
-// godoc examples
-
-func ExampleNewRelayHost() {
-	ctx := context.Background()
-
-	libp2p.New(ctx, libp2p.EnableRelay())
-}
\ No newline at end of file

From 3b53a3e995481bf28a8f8931870475ed34206a92 Mon Sep 17 00:00:00 2001
From: Mantas Vidutis <mantas.a.vidutis@gmail.com>
Date: Mon, 14 Jan 2019 09:44:02 -0800
Subject: [PATCH 3/4] move examples into test package

---
 p2p/host/relay/autorelay_test.go | 7 ++++---
 p2p/host/relay/examples_test.go  | 4 ++--
 2 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/p2p/host/relay/autorelay_test.go b/p2p/host/relay/autorelay_test.go
index 66620ca5ed..c7bbeba7dc 100644
--- a/p2p/host/relay/autorelay_test.go
+++ b/p2p/host/relay/autorelay_test.go
@@ -1,4 +1,4 @@
-package relay
+package relay_test
 
 import (
 	"context"
@@ -8,6 +8,7 @@ import (
 	"time"
 
 	libp2p "github.com/libp2p/go-libp2p"
+	relay "github.com/libp2p/go-libp2p/p2p/host/relay"
 
 	ggio "github.com/gogo/protobuf/io"
 	cid "github.com/ipfs/go-cid"
@@ -27,8 +28,8 @@ import (
 func init() {
 	autonat.AutoNATIdentifyDelay = 500 * time.Millisecond
 	autonat.AutoNATBootDelay = 1 * time.Second
-	BootDelay = 1 * time.Second
-	AdvertiseBootDelay = 1 * time.Millisecond
+	relay.BootDelay = 1 * time.Second
+	relay.AdvertiseBootDelay = 1 * time.Millisecond
 	manet.Private4 = []*net.IPNet{}
 }
 
diff --git a/p2p/host/relay/examples_test.go b/p2p/host/relay/examples_test.go
index 1309697189..6bb70993e7 100644
--- a/p2p/host/relay/examples_test.go
+++ b/p2p/host/relay/examples_test.go
@@ -1,4 +1,4 @@
-package relay
+package relay_test
 
 import (
 	"context"
@@ -29,4 +29,4 @@ func ExampleNewAutoRelayHost() {
 	opts := []libp2p.Option{libp2p.EnableRelay(), libp2p.EnableAutoRelay(), libp2p.Routing(makeRouting)}
 
 	libp2p.New(ctx, opts...)
-}
\ No newline at end of file
+}

From 168325e1091a9562a025a29097825455d3e5ce07 Mon Sep 17 00:00:00 2001
From: Mantas Vidutis <mantas.a.vidutis@gmail.com>
Date: Tue, 15 Jan 2019 08:45:08 -0800
Subject: [PATCH 4/4] review notes

---
 p2p/host/relay/autorelay.go     | 4 ++--
 p2p/host/relay/examples_test.go | 8 +++++---
 p2p/host/relay/relay.go         | 5 ++---
 3 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/p2p/host/relay/autorelay.go b/p2p/host/relay/autorelay.go
index 6603b1a92d..1681530ef9 100644
--- a/p2p/host/relay/autorelay.go
+++ b/p2p/host/relay/autorelay.go
@@ -57,8 +57,8 @@ type AutoRelayHost struct {
 }
 
 // Warning:  This function should not be used directly by clients activating
-// autorelay. NewAutoRelayHost is used internally by the libp2p.config.NewNode
-// generator. To enable autorelay, use the EnableAutoRelay Option.
+// 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{
diff --git a/p2p/host/relay/examples_test.go b/p2p/host/relay/examples_test.go
index 6bb70993e7..9ff17defb4 100644
--- a/p2p/host/relay/examples_test.go
+++ b/p2p/host/relay/examples_test.go
@@ -2,6 +2,7 @@ package relay_test
 
 import (
 	"context"
+	"github.com/libp2p/go-libp2p-circuit"
 
 	libp2p "github.com/libp2p/go-libp2p"
 
@@ -11,12 +12,14 @@ import (
 
 func ExampleNewRelayHost() {
 	ctx := context.Background()
+	var relayOpts []relay.RelayOpt
 
-	libp2p.New(ctx, libp2p.EnableRelay())
+	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
@@ -26,7 +29,6 @@ func ExampleNewAutoRelayHost() {
 		return mr, nil
 	}
 
-	opts := []libp2p.Option{libp2p.EnableRelay(), libp2p.EnableAutoRelay(), libp2p.Routing(makeRouting)}
-
+	opts := []libp2p.Option{libp2p.EnableRelay(relayOpts...), libp2p.EnableAutoRelay(), libp2p.Routing(makeRouting)}
 	libp2p.New(ctx, opts...)
 }
diff --git a/p2p/host/relay/relay.go b/p2p/host/relay/relay.go
index 8733173460..69fbe07c3d 100644
--- a/p2p/host/relay/relay.go
+++ b/p2p/host/relay/relay.go
@@ -23,9 +23,8 @@ type RelayHost struct {
 }
 
 // Warning:  This function should not be used directly by clients activating
-// relay. NewRelayHost is used internally by the libp2p.config.NewNode
-// generator. To enable relay, use the EnableRelay Option.
-// https://godoc.org/github.com/libp2p/go-libp2p#EnableRelay
+// 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,