diff --git a/limiter_test.go b/limiter_test.go
index 6ee6349a7b52afb20fd58a917d6c36c54b9169f8..f5fc18746f702fdb8ab6538cb673275f25498d43 100644
--- a/limiter_test.go
+++ b/limiter_test.go
@@ -63,10 +63,10 @@ func hangDialFunc(hang chan struct{}) dialfunc {
 
 		if tcpPortOver(a, 10) {
 			return conn.Conn(nil), nil
-		} else {
-			<-hang
-			return nil, fmt.Errorf("test bad dial")
 		}
+
+		<-hang
+		return nil, fmt.Errorf("test bad dial")
 	}
 }
 
@@ -127,7 +127,7 @@ func TestFDLimiting(t *testing.T) {
 
 	bads := []ma.Multiaddr{addrWithPort(t, 1), addrWithPort(t, 2), addrWithPort(t, 3), addrWithPort(t, 4)}
 	pids := []peer.ID{"testpeer1", "testpeer2", "testpeer3", "testpeer4"}
-	good_tcp := addrWithPort(t, 20)
+	goodTCP := addrWithPort(t, 20)
 
 	ctx := context.Background()
 	resch := make(chan dialResult)
@@ -143,7 +143,7 @@ func TestFDLimiting(t *testing.T) {
 		l.AddDialJob(&dialJob{
 			ctx:  ctx,
 			peer: pid,
-			addr: good_tcp,
+			addr: goodTCP,
 			resp: resch,
 		})
 	}
@@ -175,10 +175,10 @@ func TestTokenRedistribution(t *testing.T) {
 	df := func(ctx context.Context, p peer.ID, a ma.Multiaddr) (conn.Conn, error) {
 		if tcpPortOver(a, 10) {
 			return (conn.Conn)(nil), nil
-		} else {
-			<-hangchs[p]
-			return nil, fmt.Errorf("test bad dial")
 		}
+
+		<-hangchs[p]
+		return nil, fmt.Errorf("test bad dial")
 	}
 	l := newDialLimiterWithParams(df, 8, 4)
 
@@ -264,10 +264,10 @@ func TestStressLimiter(t *testing.T) {
 	df := func(ctx context.Context, p peer.ID, a ma.Multiaddr) (conn.Conn, error) {
 		if tcpPortOver(a, 1000) {
 			return conn.Conn(nil), nil
-		} else {
-			time.Sleep(time.Millisecond * time.Duration(5+rand.Intn(100)))
-			return nil, fmt.Errorf("test bad dial")
 		}
+
+		time.Sleep(time.Millisecond * time.Duration(5+rand.Intn(100)))
+		return nil, fmt.Errorf("test bad dial")
 	}
 
 	l := newDialLimiterWithParams(df, 20, 5)
diff --git a/swarm.go b/swarm.go
index a86edb372faa7997a4c3b592aace24426ce10f1f..704beb761e6f5f91684f16a6385021098afd0689 100644
--- a/swarm.go
+++ b/swarm.go
@@ -1,4 +1,4 @@
-// package swarm implements a connection muxer with a pair of channels
+// Package swarm implements a connection muxer with a pair of channels
 // to synchronize all network communication.
 package swarm
 
@@ -34,6 +34,8 @@ import (
 
 var log = logging.Logger("swarm2")
 
+// PSTransport is the default peerstream transport that will be used by
+// any libp2p swarms.
 var PSTransport pst.Transport
 
 func init() {
@@ -143,6 +145,8 @@ func (s *Swarm) teardown() error {
 	return s.swarm.Close()
 }
 
+// AddAddrFilter adds a multiaddr filter to the set of filters the swarm will
+// use to determine which addresses not to dial to.
 func (s *Swarm) AddAddrFilter(f string) error {
 	m, err := mafilter.NewMask(f)
 	if err != nil {
@@ -165,6 +169,7 @@ func filterAddrs(listenAddrs []ma.Multiaddr) ([]ma.Multiaddr, error) {
 	return listenAddrs, nil
 }
 
+// Listen sets up listeners for all of the given addresses
 func (s *Swarm) Listen(addrs ...ma.Multiaddr) error {
 	addrs, err := filterAddrs(addrs)
 	if err != nil {
@@ -286,6 +291,7 @@ func (s *Swarm) LocalPeer() peer.ID {
 	return s.local
 }
 
+// Backoff returns the dialbackoff object for this swarm.
 func (s *Swarm) Backoff() *dialbackoff {
 	return &s.backf
 }
diff --git a/swarm_addr.go b/swarm_addr.go
index 85d4aafe8589c8b3224cf4564a8ac61aef02761a..39fbe02afc8988e35123453eb4ae974f64976cf3 100644
--- a/swarm_addr.go
+++ b/swarm_addr.go
@@ -25,15 +25,3 @@ func (s *Swarm) ListenAddresses() []ma.Multiaddr {
 func (s *Swarm) InterfaceListenAddresses() ([]ma.Multiaddr, error) {
 	return addrutil.ResolveUnspecifiedAddresses(s.ListenAddresses(), nil)
 }
-
-// checkNATWarning checks if our observed addresses differ. if so,
-// informs the user that certain things might not work yet
-func checkNATWarning(s *Swarm, observed ma.Multiaddr, expected ma.Multiaddr) {
-	listen, err := s.InterfaceListenAddresses()
-	if err != nil {
-		log.Debugf("Error retrieving swarm.InterfaceListenAddresses: %s", err)
-		return
-	}
-
-	addrutil.CheckNATWarning(observed, expected, listen)
-}
diff --git a/swarm_addr_test.go b/swarm_addr_test.go
index 37eacbfd71d97606fd8121293914eb00044a9373..772413b286d7f8a1274c0915ada7123cc840f1cc 100644
--- a/swarm_addr_test.go
+++ b/swarm_addr_test.go
@@ -113,7 +113,7 @@ func TestDialBadAddrs(t *testing.T) {
 		p := testutil.RandPeerIDFatal(t)
 		s.peers.AddAddr(p, a, pstore.PermanentAddrTTL)
 		if _, err := s.Dial(ctx, p); err == nil {
-			t.Error("swarm should not dial: %s", m)
+			t.Errorf("swarm should not dial: %s", p)
 		}
 	}
 
diff --git a/swarm_conn.go b/swarm_conn.go
index 36932784c9612cba01e2115a5e7e16e3a393e875..762ba6e1d312758b4f82b1134a78547bbad1c068 100644
--- a/swarm_conn.go
+++ b/swarm_conn.go
@@ -13,7 +13,7 @@ import (
 	context "golang.org/x/net/context"
 )
 
-// a Conn is a simple wrapper around a ps.Conn that also exposes
+// Conn is a simple wrapper around a ps.Conn that also exposes
 // some of the methods from the underlying conn.Conn.
 // There's **five** "layers" to each connection:
 //  * 0. the net.Conn - underlying net.Conn (TCP/UDP/UTP/etc)
@@ -87,6 +87,7 @@ func (c *Conn) NewStream() (inet.Stream, error) {
 	return inet.Stream(s), err
 }
 
+// Close closes the underlying stream connection
 func (c *Conn) Close() error {
 	return c.StreamConn().Close()
 }
diff --git a/swarm_dial.go b/swarm_dial.go
index 2f4d29fa51e483a8506d9c94fa32a8ea665aaebc..67747212478b9c926174cbed13c64b07dfb3248a 100644
--- a/swarm_dial.go
+++ b/swarm_dial.go
@@ -26,9 +26,15 @@ import (
 //                                                             retry dialAttempt x
 
 var (
+	// ErrDialBackoff is returned by the backoff code when a given peer has
+	// been dialed too frequently
 	ErrDialBackoff = errors.New("dial backoff")
-	ErrDialFailed  = errors.New("dial attempt failed")
-	ErrDialToSelf  = errors.New("dial to self attempted")
+
+	// ErrDialFailed is returned when connecting to a peer has ultimately failed
+	ErrDialFailed = errors.New("dial attempt failed")
+
+	// ErrDialToSelf is returned if we attempt to dial our own peer
+	ErrDialToSelf = errors.New("dial to self attempted")
 )
 
 // dialAttempts governs how many times a goroutine will try to dial a given peer.
@@ -45,7 +51,7 @@ const defaultPerPeerRateLimit = 8
 // DialTimeout is the amount of time each dial attempt has. We can think about making
 // this larger down the road, or putting more granular timeouts (i.e. within each
 // subcomponent of Dial)
-var DialTimeout time.Duration = time.Second * 10
+var DialTimeout = time.Second * 10
 
 // dialsync is a small object that helps manage ongoing dials.
 // this way, if we receive many simultaneous dial requests, one
@@ -320,13 +326,13 @@ func (s *Swarm) dial(ctx context.Context, p peer.ID) (*Conn, error) {
 	}
 
 	ila, _ := s.InterfaceListenAddresses()
-	subtract_filter := addrutil.SubtractFilter(append(ila, s.peers.Addrs(s.local)...)...)
+	subtractFilter := addrutil.SubtractFilter(append(ila, s.peers.Addrs(s.local)...)...)
 
 	// get live channel of addresses for peer, filtered by the given filters
 	/*
 		remoteAddrChan := s.peers.AddrsChan(ctx, p,
 			addrutil.AddrUsableFilter,
-			subtract_filter,
+			subtractFilter,
 			s.Filters.AddrBlocked)
 	*/
 
@@ -339,13 +345,13 @@ func (s *Swarm) dial(ctx context.Context, p peer.ID) (*Conn, error) {
 		that we previously had (halting a dial when we run out of addrs)
 	*/
 	paddrs := s.peers.Addrs(p)
-	good_addrs := addrutil.FilterAddrs(paddrs,
+	goodAddrs := addrutil.FilterAddrs(paddrs,
 		addrutil.AddrUsableFunc,
-		subtract_filter,
+		subtractFilter,
 		addrutil.FilterNeg(s.Filters.AddrBlocked),
 	)
-	remoteAddrChan := make(chan ma.Multiaddr, len(good_addrs))
-	for _, a := range good_addrs {
+	remoteAddrChan := make(chan ma.Multiaddr, len(goodAddrs))
+	for _, a := range goodAddrs {
 		remoteAddrChan <- a
 	}
 	close(remoteAddrChan)
diff --git a/swarm_net.go b/swarm_net.go
index 8624dedba1c61dcb91fae14c98b05b9047060fc4..48defb11ad8efb0cc66c8102bf7f7bcc656a7dbb 100644
--- a/swarm_net.go
+++ b/swarm_net.go
@@ -63,7 +63,7 @@ func (n *Network) Peers() []peer.ID {
 	return n.Swarm().Peers()
 }
 
-// Peers returns the Peerstore, which tracks known peers
+// Peerstore returns the Peerstore, which tracks known peers
 func (n *Network) Peerstore() pstore.Peerstore {
 	return n.Swarm().peers
 }
@@ -142,7 +142,7 @@ func (n *Network) NewStream(ctx context.Context, p peer.ID) (inet.Stream, error)
 	return inet.Stream(s), nil
 }
 
-// SetHandler sets the protocol handler on the Network's Muxer.
+// SetStreamHandler sets the protocol handler on the Network's Muxer.
 // This operation is threadsafe.
 func (n *Network) SetStreamHandler(h inet.StreamHandler) {
 	n.Swarm().SetStreamHandler(h)
diff --git a/swarm_stream.go b/swarm_stream.go
index b305bf917e95a455c6b135f6d24c96ca5921094f..86719819a512b57191974b1ddd39cf1f75ed8683 100644
--- a/swarm_stream.go
+++ b/swarm_stream.go
@@ -6,7 +6,7 @@ import (
 	ps "github.com/jbenet/go-peerstream"
 )
 
-// a Stream is a wrapper around a ps.Stream that exposes a way to get
+// Stream is a wrapper around a ps.Stream that exposes a way to get
 // our Conn and Swarm (instead of just the ps.Conn and ps.Swarm)
 type Stream struct {
 	stream   *ps.Stream