add some documentation

dial.go

@@ -14,10 +14,18 @@ type dialer interface {
 	DialContext(ctx context.Context, network, addr string) (net.Conn, error)
 }
 
+// Dial dials the given multiaddr, reusing ports we're currently listening on if
+// possible.
+//
+// Dial attempts to be smart about choosing the source port. For example, If
+// we're dialing a loopback address and we're listening on one or more loopback
+// ports, Dial will randomly choose one of the loopback ports and addresses and
+// reuse it.
 func (t *Transport) Dial(raddr ma.Multiaddr) (manet.Conn, error) {
 	return t.DialContext(context.Background(), raddr)
 }
 
+// DialContext is like Dial but takes a context.
 func (t *Transport) DialContext(ctx context.Context, raddr ma.Multiaddr) (manet.Conn, error) {
 	network, addr, err := manet.DialArgs(raddr)
 	if err != nil {

listen.go

@@ -20,6 +20,13 @@ func (l *listener) Close() error {
 	return l.Listener.Close()
 }
 
+// Listen listens on the given multiaddr.
+//
+// If reuseport is supported, it will be enabled for this listener and future
+// dials from this transport may reuse the port.
+//
+// Note: You can listen on the same multiaddr as many times as you want
+// (although only *one* listener will end up handling the inbound connection).
 func (t *Transport) Listen(laddr ma.Multiaddr) (manet.Listener, error) {
 	nw, naddr, err := manet.DialArgs(laddr)
 	if err != nil {