[p2p] add godoc comments to Listener (#1828)

* update changelog

* document p2p/listener

* do not expose underlying net.Listener

* add a TODO

* replace todo with a comment

CHANGELOG.md

@@ -17,6 +17,7 @@ BREAKING CHANGES:
 
 IMPROVEMENT
 - [rpc/client] Supports https and wss now.
+- [p2p] Add IPv6 support to peering.
 
 ## 0.21.0
 

node/node.go

@@ -696,7 +696,7 @@ func (n *Node) makeNodeInfo(nodeID p2p.ID) p2p.NodeInfo {
 	}
 
 	p2pListener := n.sw.Listeners()[0]
-	p2pHost := p2pListener.ExternalAddressToString()
+	p2pHost := p2pListener.ExternalAddressHost()
 	p2pPort := p2pListener.ExternalAddress().Port
 	nodeInfo.ListenAddr = cmn.Fmt("%v:%v", p2pHost, p2pPort)
 

p2p/listener.go

@@ -12,16 +12,22 @@ import (
 	"github.com/tendermint/tmlibs/log"
 )
 
+// Listener is a network listener for stream-oriented protocols, providing
+// convenient methods to get listener's internal and external addresses.
+// Clients are supposed to read incoming connections from a channel, returned
+// by Connections() method.
 type Listener interface {
 	Connections() <-chan net.Conn
 	InternalAddress() *NetAddress
 	ExternalAddress() *NetAddress
-	ExternalAddressToString() string
+	ExternalAddressHost() string
 	String() string
 	Stop() error
 }
 
-// Implements Listener
+// DefaultListener is a cmn.Service, running net.Listener underneath.
+// Optionally, UPnP is used upon calling NewDefaultListener to resolve external
+// address.
 type DefaultListener struct {
 	cmn.BaseService
 
@@ -31,6 +37,8 @@ type DefaultListener struct {
 	connections chan net.Conn
 }
 
+var _ Listener = (*DefaultListener)(nil)
+
 const (
 	numBufferedConnections = 10
 	defaultExternalPort    = 8770
@@ -49,7 +57,8 @@ func splitHostPort(addr string) (host string, port int) {
 	return host, port
 }
 
-// UPNP: If false, does not try getUPNPExternalAddress()
+// NewDefaultListener creates a new DefaultListener on lAddr, optionally trying
+// to determine external address using UPnP.
 func NewDefaultListener(protocol string, lAddr string, UPNP bool, logger log.Logger) Listener {
 	// Local listen IP & port
 	lAddrIP, lAddrPort := splitHostPort(lAddr)
@@ -109,6 +118,8 @@ func NewDefaultListener(protocol string, lAddr string, UPNP bool, logger log.Log
 	return dl
 }
 
+// OnStart implements cmn.Service by spinning a goroutine, listening for new
+// connections.
 func (l *DefaultListener) OnStart() error {
 	if err := l.BaseService.OnStart(); err != nil {
 		return err
@@ -117,6 +128,7 @@ func (l *DefaultListener) OnStart() error {
 	return nil
 }
 
+// OnStop implements cmn.Service by closing the listener.
 func (l *DefaultListener) OnStop() {
 	l.BaseService.OnStop()
 	l.listener.Close() // nolint: errcheck
@@ -147,21 +159,27 @@ func (l *DefaultListener) listenRoutine() {
 	}
 }
 
-// A channel of inbound connections.
+// Connections returns a channel of inbound connections.
 // It gets closed when the listener closes.
 func (l *DefaultListener) Connections() <-chan net.Conn {
 	return l.connections
 }
 
+// InternalAddress returns the internal NetAddress (address used for
+// listening).
 func (l *DefaultListener) InternalAddress() *NetAddress {
 	return l.intAddr
 }
 
+// ExternalAddress returns the external NetAddress (publicly available,
+// determined using either UPnP or local resolver).
 func (l *DefaultListener) ExternalAddress() *NetAddress {
 	return l.extAddr
 }
 
-func (l *DefaultListener) ExternalAddressToString() string {
+// ExternalAddressHost returns the external NetAddress IP string. If an IP is
+// IPv6, it's wrapped in brackets ("[2001:db8:1f70::999:de8:7648:6e8]").
+func (l *DefaultListener) ExternalAddressHost() string {
 	ip := l.ExternalAddress().IP
 	if isIpv6(ip) {
 		// Means it's ipv6, so format it with brackets
@@ -170,12 +188,6 @@ func (l *DefaultListener) ExternalAddressToString() string {
 	return ip.String()
 }
 
-// NOTE: The returned listener is already Accept()'ing.
-// So it's not suitable to pass into http.Serve().
-func (l *DefaultListener) NetListener() net.Listener {
-	return l.listener
-}
-
 func (l *DefaultListener) String() string {
 	return fmt.Sprintf("Listener(@%v)", l.extAddr)
 }