all: fix docstrings

p2p/discover/v4wire/v4wire.go

@@ -102,7 +102,7 @@ type (
 	}
 )
 
-// This number is the maximum number of neighbor nodes in a Neighbors packet.
+// MaxNeighbors is the maximum number of neighbor nodes in a Neighbors packet.
 const MaxNeighbors = 12
 
 // This code computes the MaxNeighbors constant value.
@@ -161,8 +161,9 @@ func NewEndpoint(addr *net.UDPAddr, tcpPort uint16) Endpoint {
 }
 
 type Packet interface {
-	// packet name and type for logging purposes.
+	// Name is the name of the package, for logging purposes.
 	Name() string
+	// Kind is the packet type, for logging purposes.
 	Kind() byte
 }
 

p2p/discover/v5_udp.go

@@ -54,7 +54,7 @@ type codecV5 interface {
 	// Encode encodes a packet.
 	Encode(enode.ID, string, v5wire.Packet, *v5wire.Whoareyou) ([]byte, v5wire.Nonce, error)
 
-	// decode decodes a packet. It returns a *v5wire.Unknown packet if decryption fails.
+	// Decode decodes a packet. It returns a *v5wire.Unknown packet if decryption fails.
 	// The *enode.Node return value is non-nil when the input contains a handshake response.
 	Decode([]byte, string) (enode.ID, *enode.Node, v5wire.Packet, error)
 }

p2p/discover/v5wire/encoding.go

@@ -118,6 +118,7 @@ var (
 
 // Public errors.
 var (
+	// ErrInvalidReqID represents error when the ID is invalid.
 	ErrInvalidReqID = errors.New("request ID larger than 8 bytes")
 )
 

p2p/discover/v5wire/msg.go

@@ -59,7 +59,7 @@ type (
 		Nonce Nonce
 	}
 
-	// WHOAREYOU contains the handshake challenge.
+	// Whoareyou contains the handshake challenge.
 	Whoareyou struct {
 		ChallengeData []byte   // Encoded challenge
 		Nonce         Nonce    // Nonce of request packet
@@ -73,13 +73,13 @@ type (
 		sent mclock.AbsTime // for handshake GC.
 	}
 
-	// PING is sent during liveness checks.
+	// Ping is sent during liveness checks.
 	Ping struct {
 		ReqID  []byte
 		ENRSeq uint64
 	}
 
-	// PONG is the reply to PING.
+	// Pong is the reply to Ping.
 	Pong struct {
 		ReqID  []byte
 		ENRSeq uint64
@@ -87,58 +87,58 @@ type (
 		ToPort uint16 // packet, which provides a way to discover the external address (after NAT).
 	}
 
-	// FINDNODE is a query for nodes in the given bucket.
+	// Findnode is a query for nodes in the given bucket.
 	Findnode struct {
 		ReqID     []byte
 		Distances []uint
 	}
 
-	// NODES is the reply to FINDNODE and TOPICQUERY.
+	// Nodes is the reply to Findnode and Topicquery.
 	Nodes struct {
 		ReqID []byte
 		Total uint8
 		Nodes []*enr.Record
 	}
 
-	// TALKREQ is an application-level request.
+	// TalkRequest is an application-level request.
 	TalkRequest struct {
 		ReqID    []byte
 		Protocol string
 		Message  []byte
 	}
 
-	// TALKRESP is the reply to TALKREQ.
+	// TalkResponse is the reply to TalkRequest.
 	TalkResponse struct {
 		ReqID   []byte
 		Message []byte
 	}
 
-	// REQUESTTICKET requests a ticket for a topic queue.
+	// RequestTicket requests a ticket for a topic queue.
 	RequestTicket struct {
 		ReqID []byte
 		Topic []byte
 	}
 
-	// TICKET is the response to REQUESTTICKET.
+	// Ticket is the response to RequestTicket.
 	Ticket struct {
 		ReqID  []byte
 		Ticket []byte
 	}
 
-	// REGTOPIC registers the sender in a topic queue using a ticket.
+	// Regtopic registers the sender in a topic queue using a ticket.
 	Regtopic struct {
 		ReqID  []byte
 		Ticket []byte
 		ENR    *enr.Record
 	}
 
-	// REGCONFIRMATION is the reply to REGTOPIC.
+	// Regconfirmation is the reply to Regtopic.
 	Regconfirmation struct {
 		ReqID      []byte
 		Registered bool
 	}
 
-	// TOPICQUERY asks for nodes with the given topic.
+	// TopicQuery asks for nodes with the given topic.
 	TopicQuery struct {
 		ReqID []byte
 		Topic []byte

p2p/enode/idscheme.go

@@ -28,17 +28,18 @@ import (
 	"golang.org/x/crypto/sha3"
 )
 
-// List of known secure identity schemes.
+// ValidSchemes is a List of known secure identity schemes.
 var ValidSchemes = enr.SchemeMap{
 	"v4": V4ID{},
 }
 
+// ValidSchemesForTesting is a List of identity schemes for testing.
 var ValidSchemesForTesting = enr.SchemeMap{
 	"v4":   V4ID{},
 	"null": NullID{},
 }
 
-// v4ID is the "v4" identity scheme.
+// V4ID is the "v4" identity scheme.
 type V4ID struct{}
 
 // SignV4 signs a record using the v4 scheme.

p2p/enode/node.go

@@ -199,7 +199,7 @@ func (n ID) String() string {
 	return fmt.Sprintf("%x", n[:])
 }
 
-// The Go syntax representation of a ID is a call to HexID.
+// GoString returns the Go syntax representation of a ID is a call to HexID.
 func (n ID) GoString() string {
 	return fmt.Sprintf("enode.HexID(\"%x\")", n[:])
 }

p2p/enode/nodedb.go

@@ -494,7 +494,7 @@ func nextNode(it iterator.Iterator) *Node {
 	return nil
 }
 
-// close flushes and closes the database files.
+// Close flushes and closes the database files.
 func (db *DB) Close() {
 	close(db.quit)
 	db.lvl.Close()

p2p/enr/entries.go

@@ -61,7 +61,7 @@ type TCP uint16
 
 func (v TCP) ENRKey() string { return "tcp" }
 
-// UDP is the "udp" key, which holds the IPv6-specific UDP port of the node.
+// TCP6 is the "tcp6" key, which holds the IPv6-specific tcp6 port of the node.
 type TCP6 uint16
 
 func (v TCP6) ENRKey() string { return "tcp6" }
@@ -71,7 +71,7 @@ type UDP uint16
 
 func (v UDP) ENRKey() string { return "udp" }
 
-// UDP is the "udp" key, which holds the IPv6-specific UDP port of the node.
+// UDP6 is the "udp6" key, which holds the IPv6-specific UDP port of the node.
 type UDP6 uint16
 
 func (v UDP6) ENRKey() string { return "udp6" }

p2p/nat/nat.go

@@ -29,7 +29,7 @@ import (
 	natpmp "github.com/jackpal/go-nat-pmp"
 )
 
-// An implementation of nat.Interface can map local ports to ports
+// Interface An implementation of nat.Interface can map local ports to ports
 // accessible from the Internet.
 type Interface interface {
 	// These methods manage a mapping between a port on the local
@@ -41,11 +41,11 @@ type Interface interface {
 	AddMapping(protocol string, extport, intport int, name string, lifetime time.Duration) error
 	DeleteMapping(protocol string, extport, intport int) error
 
-	// This method should return the external (Internet-facing)
+	// ExternalIP should return the external (Internet-facing)
 	// address of the gateway device.
 	ExternalIP() (net.IP, error)
 
-	// Should return name of the method. This is used for logging.
+	// String should return name of the method. This is used for logging.
 	String() string
 }
 

p2p/nodestate/nodestate.go

@@ -117,7 +117,7 @@ type (
 		decode func([]byte) (interface{}, error)
 	}
 
-	// stateSetup contains the list of flags and fields used by the application
+	// Setup contains the list of flags and fields used by the application
 	Setup struct {
 		Version uint
 		flags   []flagDefinition

p2p/simulations/http.go

@@ -365,7 +365,7 @@ func (s *Server) StopMocker(w http.ResponseWriter, req *http.Request) {
 	w.WriteHeader(http.StatusOK)
 }
 
-// GetMockerList returns a list of available mockers
+// GetMockers returns a list of available mockers
 func (s *Server) GetMockers(w http.ResponseWriter, req *http.Request) {
 	list := GetMockerList()
 	s.JSON(w, http.StatusOK, list)

p2p/simulations/mocker.go

@@ -36,12 +36,12 @@ var mockerList = map[string]func(net *Network, quit chan struct{}, nodeCount int
 	"boot":          boot,
 }
 
-// Lookup a mocker by its name, returns the mockerFn
+// LookupMocker looks a mocker by its name, returns the mockerFn
 func LookupMocker(mockerType string) func(net *Network, quit chan struct{}, nodeCount int) {
 	return mockerList[mockerType]
 }
 
-// Get a list of mockers (keys of the map)
+// GetMockerList returns a list of mockers (keys of the map)
 // Useful for frontend to build available mocker selection
 func GetMockerList() []string {
 	list := make([]string, 0, len(mockerList))

p2p/simulations/network.go

@@ -646,8 +646,8 @@ func (net *Network) getConn(oneID, otherID enode.ID) *Conn {
 	return net.Conns[i]
 }
 
-// InitConn(one, other) retrieves the connection model for the connection between
-// peers one and other, or creates a new one if it does not exist
+// InitConn retrieves the connection model for the connection between
+// peers 'oneID' and 'otherID', or creates a new one if it does not exist
 // the order of nodes does not matter, i.e., Conn(i,j) == Conn(j, i)
 // it checks if the connection is already up, and if the nodes are running
 // NOTE: