Merge pull request #4582 from heyitsanthony/godoc-ci

*: automate checking for broken exported godocs

.travis.yml

@@ -15,6 +15,11 @@ addons:
   apt:
     packages:
     - libpcap-dev
+    - libaspell-dev
+    - libhunspell-dev
+
+before_install:
+ - go get -v github.com/chzchzchz/goword
 
 script:
  - ./test

client/keys.go

@@ -184,7 +184,7 @@ type SetOptions struct {
 	// a TTL of 0.
 	TTL time.Duration
 
-	// When refresh is set to true a TTL value can be updated
+	// Refresh set to true means a TTL value can be updated
 	// without firing a watch or changing the node value. A
 	// value must not provided when refreshing a key.
 	Refresh bool
@@ -311,6 +311,7 @@ func (n *Node) TTLDuration() time.Duration {
 type Nodes []*Node
 
 // interfaces for sorting
+
 func (ns Nodes) Len() int           { return len(ns) }
 func (ns Nodes) Less(i, j int) bool { return ns[i].Key < ns[j].Key }
 func (ns Nodes) Swap(i, j int)      { ns[i], ns[j] = ns[j], ns[i] }

clientv3/client.go

@@ -157,7 +157,7 @@ func newClient(cfg *Config) (*Client, error) {
 	}, nil
 }
 
-// activeConnection returns the current in-use connection
+// ActiveConnection returns the current in-use connection
 func (c *Client) ActiveConnection() *grpc.ClientConn {
 	c.mu.RLock()
 	defer c.mu.RUnlock()

discovery/srv.go

@@ -28,6 +28,7 @@ var (
 	resolveTCPAddr = net.ResolveTCPAddr
 )
 
+// SRVGetCluster gets the cluster information via DNS discovery.
 // TODO(barakmich): Currently ignores priority and weight (as they don't make as much sense for a bootstrap)
 // Also doesn't do any lookups for the token (though it could)
 // Also sees each entry as a separate instance.

error/error.go

@@ -136,7 +136,7 @@ func NewError(errorCode int, cause string, index uint64) *Error {
 	}
 }
 
-// Only for error interface
+// Error is for the error interface
 func (e Error) Error() string {
 	return e.Message + " (" + e.Cause + ")"
 }

etcdctl/command/rmdir_command.go

@@ -21,7 +21,7 @@ import (
 	"github.com/coreos/etcd/client"
 )
 
-// NewRemoveCommand returns the CLI command for "rmdir".
+// NewRemoveDirCommand returns the CLI command for "rmdir".
 func NewRemoveDirCommand() cli.Command {
 	return cli.Command{
 		Name:      "rmdir",

etcdmain/config.go

@@ -84,6 +84,7 @@ type config struct {
 	maxWalFiles    uint
 	name           string
 	snapCount      uint64
+	// TickMs is the number of milliseconds between heartbeat ticks.
 	// TODO: decouple tickMs and heartbeat tick (current heartbeat tick = 1).
 	// make ticks a cluster wide configuration.
 	TickMs     uint

etcdserver/etcdhttp/httptypes/errors.go

@@ -27,7 +27,7 @@ var (
 
 type HTTPError struct {
 	Message string `json:"message"`
-	// HTTP return code
+	// Code is the HTTP status code
 	Code int `json:"-"`
 }
 

etcdserver/member.go

@@ -157,14 +157,14 @@ func nodeToMember(n *store.NodeExtern) (*Member, error) {
 	return m, nil
 }
 
-// implement sort by ID interface
+// MembersByID implements sort by ID interface
 type MembersByID []*Member
 
 func (ms MembersByID) Len() int           { return len(ms) }
 func (ms MembersByID) Less(i, j int) bool { return ms[i].ID < ms[j].ID }
 func (ms MembersByID) Swap(i, j int)      { ms[i], ms[j] = ms[j], ms[i] }
 
-// implement sort by peer urls interface
+// MembersByPeerURLs implements sort by peer urls interface
 type MembersByPeerURLs []*Member
 
 func (ms MembersByPeerURLs) Len() int { return len(ms) }

etcdserver/server.go

@@ -814,11 +814,12 @@ func (s *EtcdServer) UpdateMember(ctx context.Context, memb Member) error {
 }
 
 // Implement the RaftTimer interface
+
 func (s *EtcdServer) Index() uint64 { return atomic.LoadUint64(&s.r.index) }
 
 func (s *EtcdServer) Term() uint64 { return atomic.LoadUint64(&s.r.term) }
 
-// Only for testing purpose
+// Lead is only for testing purposes.
 // TODO: add Raft server interface to expose raft related info:
 // Index, Term, Lead, Committed, Applied, LastIndex, etc.
 func (s *EtcdServer) Lead() uint64 { return atomic.LoadUint64(&s.r.lead) }

etcdserver/stats/leader.go

@@ -24,6 +24,7 @@ import (
 // LeaderStats is used by the leader in an etcd cluster, and encapsulates
 // statistics about communication with its followers
 type LeaderStats struct {
+	// Leader is the ID of the leader in the etcd cluster.
 	// TODO(jonboulle): clarify that these are IDs, not names
 	Leader    string                    `json:"leader"`
 	Followers map[string]*FollowerStats `json:"followers"`

etcdserver/stats/server.go

@@ -27,6 +27,7 @@ import (
 // communication with other members of the cluster
 type ServerStats struct {
 	Name string `json:"name"`
+	// ID is the raft ID of the node.
 	// TODO(jonboulle): use ID instead of name?
 	ID        string         `json:"id"`
 	State     raft.StateType `json:"state"`

pkg/idutil/id.go

@@ -28,6 +28,9 @@ const (
 	suffixLen = tsLen + cntLen
 )
 
+// Generator generates unique identifiers based on counters, timestamps, and
+// a node member ID.
+//
 // The initial id is in this format:
 // High order byte is memberID, next 5 bytes are from timestamp,
 // and low order 2 bytes are 0s.

raft/progress.go

@@ -36,6 +36,8 @@ func (st ProgressStateType) String() string { return prstmap[uint64(st)] }
 // progresses of all followers, and sends entries to the follower based on its progress.
 type Progress struct {
 	Match, Next uint64
+	// State defines how the leader should interact with the follower.
+	//
 	// When in ProgressStateProbe, leader sends at most one replication message
 	// per heartbeat interval. It also probes actual progress of the follower.
 	//

raft/raft.go

@@ -103,7 +103,7 @@ type Config struct {
 	// quorum is not active for an electionTimeout.
 	CheckQuorum bool
 
-	// logger is the logger used for raft log. For multinode which
+	// Logger is the logger used for raft log. For multinode which
 	// can host multiple raft group, each raft group can have its
 	// own logger
 	Logger Logger

raft/status.go

@@ -48,6 +48,7 @@ func getStatus(r *raft) Status {
 	return s
 }
 
+// MarshalJSON translates the raft status into JSON.
 // TODO: try to simplify this by introducing ID type into raft
 func (s Status) MarshalJSON() ([]byte, error) {
 	j := fmt.Sprintf(`{"id":"%x","term":%d,"vote":"%x","commit":%d,"lead":"%x","raftState":%q,"progress":{`,

raft/storage.go

@@ -168,7 +168,7 @@ func (ms *MemoryStorage) ApplySnapshot(snap pb.Snapshot) error {
 	return nil
 }
 
-// Creates a snapshot which can be retrieved with the Snapshot() method and
+// CreateSnapshot makes a snapshot which can be retrieved with Snapshot() and
 // can be used to reconstruct the state at that point.
 // If any configuration changes have been made since the last compaction,
 // the result of the last ApplyConfChange must be passed in.

rafthttp/transport.go

@@ -299,12 +299,12 @@ func (t *Transport) SendSnapshot(m snap.Message) {
 	p.sendSnap(m)
 }
 
+// Pausable is a testing interface for pausing transport traffic.
 type Pausable interface {
 	Pause()
 	Resume()
 }
 
-// for testing
 func (t *Transport) Pause() {
 	for _, p := range t.peers {
 		p.(Pausable).Pause()

storage/backend/backend.go

@@ -107,7 +107,7 @@ func (b *backend) BatchTx() BatchTx {
 	return b.batchTx
 }
 
-// force commit the current batching tx.
+// ForceCommit forces the current batching tx to commit.
 func (b *backend) ForceCommit() {
 	b.batchTx.Commit()
 }

storage/backend/batch_tx.go

@@ -55,7 +55,7 @@ func (t *batchTx) UnsafeCreateBucket(name []byte) {
 	t.pending++
 }
 
-// before calling unsafePut, the caller MUST hold the lock on tx.
+// UnsafePut must be called holding the lock on the tx.
 func (t *batchTx) UnsafePut(bucketName []byte, key []byte, value []byte) {
 	bucket := t.tx.Bucket(bucketName)
 	if bucket == nil {
@@ -67,7 +67,7 @@ func (t *batchTx) UnsafePut(bucketName []byte, key []byte, value []byte) {
 	t.pending++
 }
 
-// before calling unsafeRange, the caller MUST hold the lock on tx.
+// UnsafeRange must be called holding the lock on the tx.
 func (t *batchTx) UnsafeRange(bucketName []byte, key, endKey []byte, limit int64) (keys [][]byte, vs [][]byte) {
 	bucket := t.tx.Bucket(bucketName)
 	if bucket == nil {
@@ -94,7 +94,7 @@ func (t *batchTx) UnsafeRange(bucketName []byte, key, endKey []byte, limit int64
 	return keys, vs
 }
 
-// before calling unsafeDelete, the caller MUST hold the lock on tx.
+// UnsafeDelete must be called holding the lock on the tx.
 func (t *batchTx) UnsafeDelete(bucketName []byte, key []byte) {
 	bucket := t.tx.Bucket(bucketName)
 	if bucket == nil {

storage/watcher.go

@@ -85,6 +85,7 @@ type watchStream struct {
 	cancels map[WatchID]cancelFunc
 }
 
+// Watch creates a new watcher in the stream and returns its WatchID.
 // TODO: return error if ws is closed?
 func (ws *watchStream) Watch(key []byte, prefix bool, startRev int64) WatchID {
 	ws.mu.Lock()

store/node_extern.go

@@ -102,6 +102,7 @@ func (eNode *NodeExtern) Clone() *NodeExtern {
 type NodeExterns []*NodeExtern
 
 // interfaces for sorting
+
 func (ns NodeExterns) Len() int {
 	return len(ns)
 }

store/stats.go

@@ -40,30 +40,37 @@ const (
 type Stats struct {
 
 	// Number of get requests
+
 	GetSuccess uint64 `json:"getsSuccess"`
 	GetFail    uint64 `json:"getsFail"`
 
 	// Number of sets requests
+
 	SetSuccess uint64 `json:"setsSuccess"`
 	SetFail    uint64 `json:"setsFail"`
 
 	// Number of delete requests
+
 	DeleteSuccess uint64 `json:"deleteSuccess"`
 	DeleteFail    uint64 `json:"deleteFail"`
 
 	// Number of update requests
+
 	UpdateSuccess uint64 `json:"updateSuccess"`
 	UpdateFail    uint64 `json:"updateFail"`
 
 	// Number of create requests
+
 	CreateSuccess uint64 `json:"createSuccess"`
 	CreateFail    uint64 `json:"createFail"`
 
 	// Number of testAndSet requests
+
 	CompareAndSwapSuccess uint64 `json:"compareAndSwapSuccess"`
 	CompareAndSwapFail    uint64 `json:"compareAndSwapFail"`
 
 	// Number of compareAndDelete requests
+
 	CompareAndDeleteSuccess uint64 `json:"compareAndDeleteSuccess"`
 	CompareAndDeleteFail    uint64 `json:"compareAndDeleteFail"`
 

store/store.go

@@ -81,7 +81,7 @@ type store struct {
 	readonlySet    types.Set
 }
 
-// The given namespaces will be created as initial directories in the returned store.
+// New creates a store where the given namespaces will be created as initial directories.
 func New(namespaces ...string) Store {
 	s := newStore(namespaces...)
 	s.clock = clockwork.NewRealClock()
@@ -107,7 +107,7 @@ func (s *store) Version() int {
 	return s.CurrentVersion
 }
 
-// Retrieves current of the store
+// Index retrieves the current index of the store.
 func (s *store) Index() uint64 {
 	s.worldLock.RLock()
 	defer s.worldLock.RUnlock()

test

@@ -89,6 +89,18 @@ function fmt_tests {
 		fi
 	done
 
+	echo "Checking goword..."
+	# get all go files to process
+	gofiles=`find $FMT -iname '*.go' 2>/dev/null`
+	# ignore tests and protobuf files
+	gofiles=`echo ${gofiles} | sort | uniq | sed "s/ /\n/g" | egrep -v "(\\_test.go|\\.pb\\.go)"`
+	# only check for broken exported godocs
+	gowordRes=`goword -use-spell=false ${gofiles} | grep godoc-export | sort`
+	if [ ! -z "$gowordRes" ]; then
+		echo -e "goword checking failed:\n${gowordRes}"
+		exit 255
+	fi
+
 	echo "Checking for license header..."
 	licRes=$(for file in $(find . -type f -iname '*.go' ! -path './Godeps/*'); do
 			head -n3 "${file}" | grep -Eq "(Copyright|generated|GENERATED)" || echo -e "  ${file}"