Godocs for core packages (#3)

Godocs for core packages.

connmgr/connmgr.go

@@ -1,3 +1,9 @@
+// Package connmgr provides connection tracking and management interfaces for libp2p.
+//
+// The ConnManager interface exported from this package allows libp2p to enforce an
+// upper bound on the total number of open connections. To avoid service disruptions,
+// connections can be tagged with metadata and optionally "protected" to ensure that
+// essential connections are not arbitrarily cut.
 package connmgr
 
 import (
@@ -12,6 +18,8 @@ import (
 // with each peer.
 //
 // It enables connections to be trimmed based on implementation-defined heuristics.
+// The ConnManager allows libp2p to enforce an upper bound on the total number of
+// open connections.
 type ConnManager interface {
 
 	// TagPeer tags a peer with a string, associating a weight with the tag.

connmgr/null.go

@@ -7,6 +7,7 @@ import (
 	"github.com/libp2p/go-libp2p-core/peer"
 )
 
+// NullConnMgr is a ConnMgr that provides no functionality.
 type NullConnMgr struct{}
 
 var _ ConnManager = (*NullConnMgr)(nil)

crypto/ed25519.go

@@ -21,7 +21,7 @@ type Ed25519PublicKey struct {
 	k ed25519.PublicKey
 }
 
-// GenerateEd25519Key generate a new ed25519 private and public key pair.
+// GenerateEd25519Key generates a new ed25519 private and public key pair.
 func GenerateEd25519Key(src io.Reader) (PrivKey, PubKey, error) {
 	pub, priv, err := ed25519.GenerateKey(src)
 	if err != nil {

crypto/key.go

@@ -1,6 +1,6 @@
-// Package crypto implements various cryptographic utilities used by ipfs.
-// This includes a Public and Private key interface and an RSA key implementation
-// that satisfies it.
+// Package crypto implements various cryptographic utilities used by libp2p.
+// This includes a Public and Private key interface and key implementations
+// for supported key algorithms.
 package crypto
 
 import (
@@ -86,8 +86,7 @@ type Key interface {
 	Type() pb.KeyType
 }
 
-// PrivKey represents a private key that can be used to generate a public key,
-// sign data, and decrypt data that was encrypted with a public key
+// PrivKey represents a private key that can be used to generate a public key and sign data
 type PrivKey interface {
 	Key
 
@@ -98,7 +97,7 @@ type PrivKey interface {
 	GetPublic() PubKey
 }
 
-// PubKey is a public key
+// PubKey is a public key that can be used to verifiy data signed with the corresponding private key
 type PubKey interface {
 	Key
 
@@ -194,7 +193,7 @@ func KeyStretcher(cipherType string, hashType string, secret []byte) (StretchedK
 		cipherKeySize = 32
 	case "Blowfish":
 		ivSize = 8
-		// Note: 24 arbitrarily selected, needs more thought
+		// Note: cypherKeySize arbitrarily selected, needs more thought
 		cipherKeySize = 32
 	}
 
@@ -340,7 +339,7 @@ func ConfigEncodeKey(b []byte) string {
 	return base64.StdEncoding.EncodeToString(b)
 }
 
-// KeyEqual checks whether two
+// KeyEqual checks whether two Keys are equivalent (have identical byte representations).
 func KeyEqual(k1, k2 Key) bool {
 	if k1 == k2 {
 		return true

crypto/rsa.go

@@ -18,18 +18,18 @@ import (
 // hash so this is a reasonable absolute minimum.
 var ErrRsaKeyTooSmall = errors.New("rsa keys must be >= 512 bits to be useful")
 
-// RsaPrivateKey is an rsa private key
+// RsaPrivateKey is an RSA private key.
 type RsaPrivateKey struct {
 	sk *rsa.PrivateKey
 	pk *rsa.PublicKey
 }
 
-// RsaPublicKey is an rsa public key
+// RsaPublicKey is an RSA public key.
 type RsaPublicKey struct {
 	k *rsa.PublicKey
 }
 
-// GenerateRSAKeyPair generates a new rsa private and public key
+// GenerateRSAKeyPair generates a new RSA private and public key.
 func GenerateRSAKeyPair(bits int, src io.Reader) (PrivKey, PubKey, error) {
 	if bits < 512 {
 		return nil, nil, ErrRsaKeyTooSmall
@@ -42,7 +42,9 @@ func GenerateRSAKeyPair(bits int, src io.Reader) (PrivKey, PubKey, error) {
 	return &RsaPrivateKey{sk: priv}, &RsaPublicKey{pk}, nil
 }
 
-// Verify compares a signature against input data
+// Verify compares a signature against input data.
+// In the case of RSA keys, verification applies PKCS1v15 RSA signature verification
+// upon the SHA-256 hash of the input data.
 func (pk *RsaPublicKey) Verify(data, sig []byte) (bool, error) {
 	hashed := sha256.Sum256(data)
 	err := rsa.VerifyPKCS1v15(pk.k, crypto.SHA256, hashed[:], sig)
@@ -56,32 +58,34 @@ func (pk *RsaPublicKey) Type() pb.KeyType {
 	return pb.KeyType_RSA
 }
 
-// Bytes returns protobuf bytes of a public key
+// Bytes returns protobuf bytes of a public key.
 func (pk *RsaPublicKey) Bytes() ([]byte, error) {
 	return MarshalPublicKey(pk)
 }
 
+// Raw returns a binary representation of the key in a type-specific format.
+// In the case of RSA keys, returns an X.509 PKIX encoded public key.
 func (pk *RsaPublicKey) Raw() ([]byte, error) {
 	return x509.MarshalPKIXPublicKey(pk.k)
 }
 
-// Encrypt returns encrypted bytes from the inpu data
+// Encrypt returns encrypted bytes from the input data.
 func (pk *RsaPublicKey) Encrypt(b []byte) ([]byte, error) {
 	return rsa.EncryptPKCS1v15(rand.Reader, pk.k, b)
 }
 
-// Equals checks whether this key is equal to another
+// Equals checks whether this key is equal to another.
 func (pk *RsaPublicKey) Equals(k Key) bool {
 	return KeyEqual(pk, k)
 }
 
-// Sign returns a signature of the input data
+// Sign returns a signature of the input data.
 func (sk *RsaPrivateKey) Sign(message []byte) ([]byte, error) {
 	hashed := sha256.Sum256(message)
 	return rsa.SignPKCS1v15(rand.Reader, sk.sk, crypto.SHA256, hashed[:])
 }
 
-// GetPublic returns a public key
+// GetPublic returns a public key.
 func (sk *RsaPrivateKey) GetPublic() PubKey {
 	if sk.pk == nil {
 		sk.pk = &sk.sk.PublicKey
@@ -89,7 +93,7 @@ func (sk *RsaPrivateKey) GetPublic() PubKey {
 	return &RsaPublicKey{sk.pk}
 }
 
-// Decrypt returns decrypted bytes of the input encrypted bytes
+// Decrypt returns decrypted bytes of the input encrypted bytes.
 func (sk *RsaPrivateKey) Decrypt(b []byte) ([]byte, error) {
 	return rsa.DecryptPKCS1v15(rand.Reader, sk.sk, b)
 }
@@ -98,22 +102,24 @@ func (sk *RsaPrivateKey) Type() pb.KeyType {
 	return pb.KeyType_RSA
 }
 
-// Bytes returns protobuf bytes from a private key
+// Bytes returns protobuf bytes from a private key.
 func (sk *RsaPrivateKey) Bytes() ([]byte, error) {
 	return MarshalPrivateKey(sk)
 }
 
+// Raw returns a binary representation of a private key in a type-specific format.
+// In the case of RSA keys, returns the key in ASN.1 DER encoded form.
 func (sk *RsaPrivateKey) Raw() ([]byte, error) {
 	b := x509.MarshalPKCS1PrivateKey(sk.sk)
 	return b, nil
 }
 
-// Equals checks whether this key is equal to another
+// Equals checks whether this key is equal to another.
 func (sk *RsaPrivateKey) Equals(k Key) bool {
 	return KeyEqual(sk, k)
 }
 
-// UnmarshalRsaPrivateKey returns a private key from the input x509 bytes
+// UnmarshalRsaPrivateKey returns a private key from the input X.509 bytes.
 func UnmarshalRsaPrivateKey(b []byte) (PrivKey, error) {
 	sk, err := x509.ParsePKCS1PrivateKey(b)
 	if err != nil {
@@ -125,12 +131,12 @@ func UnmarshalRsaPrivateKey(b []byte) (PrivKey, error) {
 	return &RsaPrivateKey{sk: sk}, nil
 }
 
-// MarshalRsaPrivateKey returns the x509 bytes of the private key
+// MarshalRsaPrivateKey returns the X.509 bytes of the private key.
 func MarshalRsaPrivateKey(k *RsaPrivateKey) []byte {
 	return x509.MarshalPKCS1PrivateKey(k.sk)
 }
 
-// UnmarshalRsaPublicKey returns a public key from the input x509 bytes
+// UnmarshalRsaPublicKey returns a public key from the input X.509 bytes.
 func UnmarshalRsaPublicKey(b []byte) (PubKey, error) {
 	pub, err := x509.ParsePKIXPublicKey(b)
 	if err != nil {
@@ -146,7 +152,7 @@ func UnmarshalRsaPublicKey(b []byte) (PubKey, error) {
 	return &RsaPublicKey{pk}, nil
 }
 
-// MarshalRsaPublicKey returns the x509 bytes from the public key
+// MarshalRsaPublicKey returns the X.509 bytes from the public key.
 func MarshalRsaPublicKey(k *RsaPublicKey) ([]byte, error) {
 	return x509.MarshalPKIXPublicKey(k.k)
 }

discovery/discovery.go

@@ -1,3 +1,4 @@
+// Package discovery provides service advertisement and peer discovery interfaces for libp2p.
 package discovery
 
 import (

host/host.go

@@ -1,3 +1,6 @@
+// Package host provides the core Host interface for libp2p.
+//
+// Host represents a single libp2p node in a peer-to-peer network.
 package host
 
 import (

metrics/bandwidth.go

@@ -1,3 +1,4 @@
+// Package metrics provides metrics collection and reporting interfaces for libp2p.
 package metrics
 
 import (
@@ -6,6 +7,9 @@ import (
 	"github.com/libp2p/go-libp2p-core/protocol"
 )
 
+// BandwidthCounter tracks incoming and outgoing data transferred by the local peer.
+// Metrics are available for total bandwidth across all peers / protocols, as well
+// as segmented by remote peer ID and protocol ID.
 type BandwidthCounter struct {
 	totalIn  flow.Meter
 	totalOut flow.Meter
@@ -17,28 +21,39 @@ type BandwidthCounter struct {
 	peerOut flow.MeterRegistry
 }
 
+// NewBandwidthCounter creates a new BandwidthCounter.
 func NewBandwidthCounter() *BandwidthCounter {
 	return new(BandwidthCounter)
 }
 
+// LogSentMessage records the size of an outgoing message
+// without associating the bandwidth to a specific peer or protocol.
 func (bwc *BandwidthCounter) LogSentMessage(size int64) {
 	bwc.totalOut.Mark(uint64(size))
 }
 
+// LogRecvMessage records the size of an incoming message
+// without associating the bandwith to a specific peer or protocol.
 func (bwc *BandwidthCounter) LogRecvMessage(size int64) {
 	bwc.totalIn.Mark(uint64(size))
 }
 
+// LogSentMessageStream records the size of an outgoing message over a single logical stream.
+// Bandwidth is associated with the given protocol.ID and peer.ID.
 func (bwc *BandwidthCounter) LogSentMessageStream(size int64, proto protocol.ID, p peer.ID) {
 	bwc.protocolOut.Get(string(proto)).Mark(uint64(size))
 	bwc.peerOut.Get(string(p)).Mark(uint64(size))
 }
 
+// LogRecvMessageStream records the size of an incoming message over a single logical stream.
+// Bandwidth is associated with the given protocol.ID and peer.ID.
 func (bwc *BandwidthCounter) LogRecvMessageStream(size int64, proto protocol.ID, p peer.ID) {
 	bwc.protocolIn.Get(string(proto)).Mark(uint64(size))
 	bwc.peerIn.Get(string(p)).Mark(uint64(size))
 }
 
+// GetBandwidthForPeer returns a Stats struct with bandwidth metrics associated with the given peer.ID.
+// The metrics returned include all traffic sent / received for the peer, regardless of protocol.
 func (bwc *BandwidthCounter) GetBandwidthForPeer(p peer.ID) (out Stats) {
 	inSnap := bwc.peerIn.Get(string(p)).Snapshot()
 	outSnap := bwc.peerOut.Get(string(p)).Snapshot()
@@ -51,6 +66,9 @@ func (bwc *BandwidthCounter) GetBandwidthForPeer(p peer.ID) (out Stats) {
 	}
 }
 
+// GetBandwidthForProtocol returns a Stats struct with bandwidth metrics associated with the given protocol.ID.
+// The metrics returned include all traffic sent / recieved for the protocol, regardless of which peers were
+// involved.
 func (bwc *BandwidthCounter) GetBandwidthForProtocol(proto protocol.ID) (out Stats) {
 	inSnap := bwc.protocolIn.Get(string(proto)).Snapshot()
 	outSnap := bwc.protocolOut.Get(string(proto)).Snapshot()
@@ -63,6 +81,8 @@ func (bwc *BandwidthCounter) GetBandwidthForProtocol(proto protocol.ID) (out Sta
 	}
 }
 
+// GetBandwidthTotals returns a Stats struct with bandwidth metrics for all data sent / recieved by the
+// local peer, regardless of protocol or remote peer IDs.
 func (bwc *BandwidthCounter) GetBandwidthTotals() (out Stats) {
 	inSnap := bwc.totalIn.Snapshot()
 	outSnap := bwc.totalOut.Snapshot()

metrics/reporter.go

@@ -1,3 +1,4 @@
+// Package metrics provides metrics collection and reporting interfaces for libp2p.
 package metrics
 
 import (
@@ -5,6 +6,10 @@ import (
 	"github.com/libp2p/go-libp2p-core/protocol"
 )
 
+// Stats represents a point-in-time snapshot of bandwidth metrics.
+//
+// The TotalIn and TotalOut fields record cumulative bytes sent / received.
+// The RateIn and RateOut fields record bytes sent / received per second.
 type Stats struct {
 	TotalIn  int64
 	TotalOut int64
@@ -12,6 +17,7 @@ type Stats struct {
 	RateOut  float64
 }
 
+// Reporter provides methods for logging and retrieving metrics.
 type Reporter interface {
 	LogSentMessage(int64)
 	LogRecvMessage(int64)

mux/mux.go

@@ -1,3 +1,7 @@
+// Package mux provides stream multiplexing interfaces for libp2p.
+//
+// For a conceptual overview of stream multiplexing in libp2p, see
+// https://docs.libp2p.io/concepts/stream-multiplexing/
 package mux
 
 import (
@@ -31,7 +35,16 @@ type MuxedStream interface {
 // NoopHandler do nothing. Resets streams as soon as they are opened.
 var NoopHandler = func(s MuxedStream) { s.Reset() }
 
-// MuxedConn is a stream-multiplexing connection to a remote peer.
+// MuxedConn represents a connection to a remote peer that has been
+// extended to support stream multiplexing.
+//
+// A MuxedConn allows a single net.Conn connection to carry many logically
+// independent bidirectional streams of binary data.
+//
+// Together with network.ConnSecurity, MuxedConn is a component of the
+// transport.CapableConn interface, which represents a "raw" network
+// connection that has been "upgraded" to support the libp2p capabilities
+// of secure communication and stream multiplexing.
 type MuxedConn interface {
 	// Close closes the stream muxer and the the underlying net.Conn.
 	io.Closer
@@ -47,7 +60,9 @@ type MuxedConn interface {
 	AcceptStream() (MuxedStream, error)
 }
 
-// Transport constructs go-stream-muxer compatible connections.
+// Multiplexer wraps a net.Conn with a stream multiplexing
+// implementation and returns a MuxedConn that supports opening
+// multiple streams over the underlying net.Conn
 type Multiplexer interface {
 
 	// NewConn constructs a new connection

network/errors.go

@@ -2,7 +2,7 @@ package network
 
 import "errors"
 
-// There are no addresses associated with a peer when they were needed.
+// ErrNoRemoteAddrs is returned when there are no addresses associated with a peer during a dial.
 var ErrNoRemoteAddrs = errors.New("no remote addresses")
 
 // ErrNoConn is returned when attempting to open a stream to a peer with the NoDial

network/network.go

@@ -1,3 +1,8 @@
+// Package network provides core networking abstractions for libp2p.
+//
+// The network package provides the high-level Network interface for interacting
+// with other libp2p peers, which is the primary public API for initiating and
+// accepting connections to remote peers.
 package network
 
 import (
@@ -64,7 +69,7 @@ type ConnHandler func(Conn)
 
 // Network is the interface used to connect to the outside world.
 // It dials and listens for connections. it uses a Swarm to pool
-// connnections (see swarm pkg, and peerstream.Swarm). Connections
+// connections (see swarm pkg, and peerstream.Swarm). Connections
 // are encrypted with a TLS-like protocol.
 type Network interface {
 	Dialer

peer/peer.go

@@ -34,14 +34,17 @@ var AdvancedEnableInlining = true
 const maxInlineKeyLength = 42
 
 // ID is a libp2p peer identity.
+//
+// Peer IDs are derived by hashing a peer's public key and encoding the
+// hash output as a multihash. See IDFromPublicKey for details.
 type ID string
 
-// Pretty returns a b58-encoded string of the ID
+// Pretty returns a base58-encoded string representation of the ID.
 func (id ID) Pretty() string {
 	return IDB58Encode(id)
 }
 
-// Loggable returns a pretty peerID string in loggable JSON format
+// Loggable returns a pretty peer ID string in loggable JSON format.
 func (id ID) Loggable() map[string]interface{} {
 	return map[string]interface{}{
 		"peerID": id.Pretty(),
@@ -52,7 +55,7 @@ func (id ID) String() string {
 	return id.Pretty()
 }
 
-// String prints out the peer.
+// String prints out the peer ID.
 //
 // TODO(brian): ensure correctness at ID generation and
 // enforce this by only exposing functions that generate
@@ -66,12 +69,12 @@ func (id ID) ShortString() string {
 	return fmt.Sprintf("<peer.ID %s*%s>", pid[:2], pid[len(pid)-6:])
 }
 
-// MatchesPrivateKey tests whether this ID was derived from sk
+// MatchesPrivateKey tests whether this ID was derived from the secret key sk.
 func (id ID) MatchesPrivateKey(sk ic.PrivKey) bool {
 	return id.MatchesPublicKey(sk.GetPublic())
 }
 
-// MatchesPublicKey tests whether this ID was derived from pk
+// MatchesPublicKey tests whether this ID was derived from the public key pk.
 func (id ID) MatchesPublicKey(pk ic.PubKey) bool {
 	oid, err := IDFromPublicKey(pk)
 	if err != nil {
@@ -99,7 +102,7 @@ func (id ID) ExtractPublicKey() (ic.PubKey, error) {
 	return pk, nil
 }
 
-// Validate check if ID is empty or not
+// Validate checks if ID is empty or not.
 func (id ID) Validate() error {
 	if id == ID("") {
 		return ErrEmptyPeerID
@@ -108,8 +111,8 @@ func (id ID) Validate() error {
 	return nil
 }
 
-// IDFromString cast a string to ID type, and validate
-// the id to make sure it is a multihash.
+// IDFromString casts a string to the ID type, and validates
+// the value to make sure it is a multihash.
 func IDFromString(s string) (ID, error) {
 	if _, err := mh.Cast([]byte(s)); err != nil {
 		return ID(""), err
@@ -117,8 +120,8 @@ func IDFromString(s string) (ID, error) {
 	return ID(s), nil
 }
 
-// IDFromBytes cast a string to ID type, and validate
-// the id to make sure it is a multihash.
+// IDFromBytes casts a byte slice to the ID type, and validates
+// the value to make sure it is a multihash.
 func IDFromBytes(b []byte) (ID, error) {
 	if _, err := mh.Cast(b); err != nil {
 		return ID(""), err
@@ -126,7 +129,8 @@ func IDFromBytes(b []byte) (ID, error) {
 	return ID(b), nil
 }
 
-// IDB58Decode returns a b58-decoded Peer
+// IDB58Decode accepts a base58-encoded multihash representing a peer ID
+// and returns the decoded ID if the input is valid.
 func IDB58Decode(s string) (ID, error) {
 	m, err := mh.FromB58String(s)
 	if err != nil {
@@ -135,12 +139,13 @@ func IDB58Decode(s string) (ID, error) {
 	return ID(m), err
 }
 
-// IDB58Encode returns b58-encoded string
+// IDB58Encode returns the base58-encoded multihash representation of the ID.
 func IDB58Encode(id ID) string {
 	return b58.Encode([]byte(id))
 }
 
-// IDHexDecode returns a hex-decoded Peer
+// IDHexDecode accepts a hex-encoded multihash representing a peer ID
+// and returns the decoded ID if the input is valid.
 func IDHexDecode(s string) (ID, error) {
 	m, err := mh.FromHexString(s)
 	if err != nil {
@@ -149,12 +154,12 @@ func IDHexDecode(s string) (ID, error) {
 	return ID(m), err
 }
 
-// IDHexEncode returns hex-encoded string
+// IDHexEncode returns the hex-encoded multihash representation of the ID.
 func IDHexEncode(id ID) string {
 	return hex.EncodeToString([]byte(id))
 }
 
-// IDFromPublicKey returns the Peer ID corresponding to pk
+// IDFromPublicKey returns the Peer ID corresponding to the public key pk.
 func IDFromPublicKey(pk ic.PubKey) (ID, error) {
 	b, err := pk.Bytes()
 	if err != nil {
@@ -168,7 +173,7 @@ func IDFromPublicKey(pk ic.PubKey) (ID, error) {
 	return ID(hash), nil
 }
 
-// IDFromPrivateKey returns the Peer ID corresponding to sk
+// IDFromPrivateKey returns the Peer ID corresponding to the secret key sk.
 func IDFromPrivateKey(sk ic.PrivKey) (ID, error) {
 	return IDFromPublicKey(sk.GetPublic())
 }

peerstore/peerstore.go

@@ -1,3 +1,5 @@
+// Package peerstore provides types and interfaces for local storage of address information, 
+// metadata, and public key material about libp2p peers.
 package peerstore
 
 import (

pnet/protector.go

@@ -1,3 +1,4 @@
+// Package pnet provides interfaces for private networking in libp2p.
 package pnet
 
 import "net"

protocol/switch.go

@@ -1,3 +1,4 @@
+// Package protocol provides core interfaces for protocol routing and negotiation in libp2p.
 package protocol
 
 import (
@@ -6,21 +7,74 @@ import (
 
 // HandlerFunc is a user-provided function used by the Router to
 // handle a protocol/stream.
+//
+// Will be invoked with the protocol ID string as the first argument,
+// which may differ from the ID used for registration if the handler
+// was registered using a match function.
 type HandlerFunc = func(protocol string, rwc io.ReadWriteCloser) error
 
+// Router is an interface that allows users to add and remove protocol handlers,
+// which will be invoked when incoming stream requests for registered protocols
+// are accepted.
+//
+// Upon receiving an incoming stream request, the Router will check all registered
+// protocol handlers to determine which (if any) is capable of handling the stream.
+// The handlers are checked in order of registration; if multiple handlers are
+// eligible, only the first to be registered will be invoked.
 type Router interface {
+
+	// AddHandler registers the given handler to be invoked for
+	// an exact literal match of the given protocol ID string.
 	AddHandler(protocol string, handler HandlerFunc)
+
+	// AddHandlerWithFunc registers the given handler to be invoked
+	// when the provided match function returns true.
+	//
+	// The match function will be invoked with an incoming protocol
+	// ID string, and should return true if the handler supports
+	// the protocol. Note that the protocol ID argument is not
+	// used for matching; if you want to match the protocol ID
+	// string exactly, you must check for it in your match function.
 	AddHandlerWithFunc(protocol string, match func(string) bool, handler HandlerFunc)
+
+	// RemoveHandler removes the registered handler (if any) for the
+	// given protocol ID string.
 	RemoveHandler(protocol string)
+
+	// Protocols returns a list of all registered protocol ID strings.
+	// Note that the Router may be able to handle protocol IDs not
+	// included in this list if handlers were added with match functions
+	// using AddHandlerWithFunc.
 	Protocols() []string
 }
 
+// Negotiator is a component capable of reaching agreement over what protocols
+// to use for inbound streams of communication.
 type Negotiator interface {
+
+	// NegotiateLazy will return the registered protocol handler to use
+	// for a given inbound stream, returning as soon as the protocol has been
+	// determined. Returns an error if negotiation fails.
+	//
+	// NegotiateLazy may return before all protocol negotiation responses have been
+	// written to the stream. This is in contrast to Negotiate, which will block until
+	// the Negotiator is finished with the stream.
 	NegotiateLazy(rwc io.ReadWriteCloser) (io.ReadWriteCloser, string, HandlerFunc, error)
+
+	// Negotiate will return the registered protocol handler to use for a given
+	// inbound stream, returning after the protocol has been determined and the
+	// Negotiator has finished using the stream for negotiation. Returns an
+	// error if negotiation fails.
 	Negotiate(rwc io.ReadWriteCloser) (string, HandlerFunc, error)
+
+	// Handle calls Negotiate to determine which protocol handler to use for an
+	// inbound stream, then invokes the protocol handler function, passing it
+	// the protocol ID and the stream. Returns an error if negotiation fails.
 	Handle(rwc io.ReadWriteCloser) error
 }
 
+// Switch is the component responsible for "dispatching" incoming stream requests to
+// their corresponding stream handlers. It is both a Negotiator and a Router.
 type Switch interface {
 	Router
 	Negotiator

routing/routing.go

@@ -1,4 +1,4 @@
-// package routing defines the interface for a routing system used by ipfs.
+// Package routing provides interfaces for peer routing and content routing in libp2p.
 package routing
 
 import (
@@ -20,6 +20,9 @@ var ErrNotSupported = errors.New("routing: operation or key not supported")
 
 // ContentRouting is a value provider layer of indirection. It is used to find
 // information about who has what content.
+//
+// Content is identified by CID (content identifier), which encodes a hash
+// of the identified content in a future-proof manner.
 type ContentRouting interface {
 	// Provide adds the given cid to the content routing system. If 'true' is
 	// passed, it also announces it, otherwise it is just kept in the local
@@ -30,7 +33,7 @@ type ContentRouting interface {
 	FindProvidersAsync(context.Context, cid.Cid, int) <-chan peer.AddrInfo
 }
 
-// PeerRouting is a way to find information about certain peers.
+// PeerRouting is a way to find address information about certain peers.
 // This can be implemented by a simple lookup table, a tracking server,
 // or even a DHT.
 type PeerRouting interface {
@@ -62,7 +65,7 @@ type ValueStore interface {
 	SearchValue(context.Context, string, ...Option) (<-chan []byte, error)
 }
 
-// IpfsRouting is the combination of different routing types that IPFS uses.
+// Routing is the combination of different routing types supported by libp2p.
 // It can be satisfied by a single item (such as a DHT) or multiple different
 // pieces that are more optimized to each task.
 type Routing interface {

sec/insecure/insecure.go

@@ -1,3 +1,6 @@
+// Package insecure provides an insecure, unencrypted implementation of the the SecureConn and SecureTransport interfaces.
+//
+// Recommended only for testing and other non-production usage.
 package insecure
 
 import (
@@ -15,7 +18,8 @@ import (
 const ID = "/plaintext/1.0.0"
 
 // Transport is a no-op stream security transport. It provides no
-// security and simply wraps connections in blank
+// security and simply mocks the security and identity methods to
+// return peer IDs known ahead of time.
 type Transport struct {
 	id peer.ID
 }

sec/security.go

@@ -1,3 +1,4 @@
+// Package sec provides secure connection and transport interfaces for libp2p.
 package sec
 
 import (

transport/transport.go

@@ -1,3 +1,5 @@
+// Package transport provides the Transport interface, which represents
+// the devices and network protocols used to send and recieve data.
 package transport
 
 import (
@@ -22,8 +24,17 @@ var DialTimeout = 60 * time.Second
 // protocol selection as well as the handshake, if applicable.
 var AcceptTimeout = 60 * time.Second
 
-// CapableConn is a connection that is is an extension of the net.Conn interface that provides multiaddr
-// information, and an accessor for the transport used to create the conn
+// A CapableConn represents a connection that has offers the basic
+// capabilities required by libp2p: stream multiplexing, encryption and
+// peer authentication.
+//
+// These capabilities may be natively provided by the transport, or they
+// may be shimmed via the "connection upgrade" process, which converts a
+// "raw" network connection into one that supports such capabilities by
+// layering an encryption channel and a stream multiplexer.
+//
+// CapableConn provides accessors for the local and remote multiaddrs used to
+// establish the connection and an accessor for the underlying Transport.
 type CapableConn interface {
 	mux.MuxedConn
 	network.ConnSecurity
@@ -34,9 +45,16 @@ type CapableConn interface {
 }
 
 // Transport represents any device by which you can connect to and accept
-// connections from other peers. The built-in transports provided are TCP and UTP
-// but many more can be implemented, sctp, audio signals, sneakernet, UDT, a
-// network of drones carrying usb flash drives, and so on.
+// connections from other peers.
+//
+// The Transport interface allows you to open connections to other peers
+// by dialing them, and also lets you listen for incoming connections.
+//
+// Connections returned by Dial and passed into Listeners are of type
+// CapableConn, which means that they have been upgraded to support
+// stream multiplexing and connection security (encryption and authentication).
+//
+// For a conceptual overview, see https://docs.libp2p.io/concepts/transport/
 type Transport interface {
 	// Dial dials a remote peer. It should try to reuse local listener
 	// addresses if possible but it may choose not to.
@@ -65,7 +83,7 @@ type Transport interface {
 	Proxy() bool
 }
 
-// Listener is an interface closely resembling the net.Listener interface.  The
+// Listener is an interface closely resembling the net.Listener interface. The
 // only real difference is that Accept() returns Conn's of the type in this
 // package, and also exposes a Multiaddr method as opposed to a regular Addr
 // method