From 42245a55185121ef7179413374baa72c52cc14ad Mon Sep 17 00:00:00 2001
From: Anthony Romano <anthony.romano@coreos.com>
Date: Fri, 15 Apr 2016 13:13:24 -0700
Subject: [PATCH] storagepb, etcdserverpb: improve documentation for RPC
 message fields

---
 etcdserver/etcdserverpb/rpc.pb.go | 342 ++++++++++++++++++------------
 etcdserver/etcdserverpb/rpc.proto | 239 +++++++++++++--------
 storage/storagepb/kv.pb.go        |  11 +-
 storage/storagepb/kv.proto        |   7 +
 4 files changed, 370 insertions(+), 229 deletions(-)

diff --git a/etcdserver/etcdserverpb/rpc.pb.go b/etcdserver/etcdserverpb/rpc.pb.go
index a3b2468b7..3e2935bf2 100644
--- a/etcdserver/etcdserverpb/rpc.pb.go
+++ b/etcdserver/etcdserverpb/rpc.pb.go
@@ -173,11 +173,13 @@ func (x AlarmRequest_AlarmAction) String() string {
 }
 
 type ResponseHeader struct {
+	// cluster_id is the ID of the cluster which sent the response.
 	ClusterId uint64 `protobuf:"varint,1,opt,name=cluster_id,proto3" json:"cluster_id,omitempty"`
-	MemberId  uint64 `protobuf:"varint,2,opt,name=member_id,proto3" json:"member_id,omitempty"`
-	// revision of the store when the request was applied.
+	// member_id is the ID of the member which sent the response.
+	MemberId uint64 `protobuf:"varint,2,opt,name=member_id,proto3" json:"member_id,omitempty"`
+	// revision is the key-value store revision when the request was applied.
 	Revision int64 `protobuf:"varint,3,opt,name=revision,proto3" json:"revision,omitempty"`
-	// term of raft when the request was applied.
+	// raft_term is the raft term when the request was applied.
 	RaftTerm uint64 `protobuf:"varint,4,opt,name=raft_term,proto3" json:"raft_term,omitempty"`
 }
 
@@ -186,27 +188,27 @@ func (m *ResponseHeader) String() string { return proto.CompactTextString(m) }
 func (*ResponseHeader) ProtoMessage()    {}
 
 type RangeRequest struct {
-	// if the range_end is not given, the request returns the key.
+	// key is the first key for the range. If range_end is not given, the request only looks up key.
 	Key []byte `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"`
-	// if the range_end is given, it gets the keys in range [key, range_end)
-	// if range_end is nonempty, otherwise it returns all keys >= key.
+	// range_end is the upper bound on the requested range [key, range_end).
+	// If range_end is '\0', the range is all keys >= key.
 	RangeEnd []byte `protobuf:"bytes,2,opt,name=range_end,proto3" json:"range_end,omitempty"`
-	// limit the number of keys returned.
+	// limit is a limit on the number of keys returned for the request.
 	Limit int64 `protobuf:"varint,3,opt,name=limit,proto3" json:"limit,omitempty"`
-	// range over the store at the given revision.
-	// if revision is less or equal to zero, range over the newest store.
-	// if the revision has been compacted, ErrCompaction will be returned in
-	// response.
+	// revision is the point-in-time of the key-value store to use for the range.
+	// If revision is less or equal to zero, the range is over the newest key-value store.
+	// If the revision has been compacted, ErrCompaction is returned as a response.
 	Revision int64 `protobuf:"varint,4,opt,name=revision,proto3" json:"revision,omitempty"`
-	// sort_order is the requested order for returned the results
+	// sort_order is the order for returned sorted results.
 	SortOrder RangeRequest_SortOrder `protobuf:"varint,5,opt,name=sort_order,proto3,enum=etcdserverpb.RangeRequest_SortOrder" json:"sort_order,omitempty"`
-	// sort_target is the kv field to use for sorting
+	// sort_target is the key-value field to use for sorting.
 	SortTarget RangeRequest_SortTarget `protobuf:"varint,6,opt,name=sort_target,proto3,enum=etcdserverpb.RangeRequest_SortTarget" json:"sort_target,omitempty"`
-	// range request is linearizable by default. Linearizable requests has a higher
-	// latency and lower throughput than serializable request.
-	// To reduce latency, serializable can be set. If serializable is set, range request
-	// will be serializable, but not linearizable with other requests.
-	// Serializable range can be served locally without waiting for other nodes in the cluster.
+	// serializable sets the range request to use serializable member-local reads.
+	// Range requests are linearizable by default; linearizable requests have higher
+	// latency and lower throughput than serializable requests but reflect the current
+	// consensus of the cluster. For better performance, in exchange for possible stale reads,
+	// a serializable range request is served locally without needing to reach consensus
+	// with other nodes in the cluster.
 	Serializable bool `protobuf:"varint,7,opt,name=serializable,proto3" json:"serializable,omitempty"`
 }
 
@@ -215,8 +217,9 @@ func (m *RangeRequest) String() string { return proto.CompactTextString(m) }
 func (*RangeRequest) ProtoMessage()    {}
 
 type RangeResponse struct {
-	Header *ResponseHeader       `protobuf:"bytes,1,opt,name=header" json:"header,omitempty"`
-	Kvs    []*storagepb.KeyValue `protobuf:"bytes,2,rep,name=kvs" json:"kvs,omitempty"`
+	Header *ResponseHeader `protobuf:"bytes,1,opt,name=header" json:"header,omitempty"`
+	// kvs is the list of key-value pairs matched by the range request.
+	Kvs []*storagepb.KeyValue `protobuf:"bytes,2,rep,name=kvs" json:"kvs,omitempty"`
 	// more indicates if there are more keys to return in the requested range.
 	More bool `protobuf:"varint,3,opt,name=more,proto3" json:"more,omitempty"`
 }
@@ -240,9 +243,13 @@ func (m *RangeResponse) GetKvs() []*storagepb.KeyValue {
 }
 
 type PutRequest struct {
-	Key   []byte `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"`
+	// key is the key, in bytes, to put into the key-value store.
+	Key []byte `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"`
+	// value is the value, in bytes, to associate with the key in the key-value store.
 	Value []byte `protobuf:"bytes,2,opt,name=value,proto3" json:"value,omitempty"`
-	Lease int64  `protobuf:"varint,3,opt,name=lease,proto3" json:"lease,omitempty"`
+	// lease is the lease ID to associate with the key in the key-value store. A lease
+	// value of 0 indicates no lease.
+	Lease int64 `protobuf:"varint,3,opt,name=lease,proto3" json:"lease,omitempty"`
 }
 
 func (m *PutRequest) Reset()         { *m = PutRequest{} }
@@ -265,9 +272,11 @@ func (m *PutResponse) GetHeader() *ResponseHeader {
 }
 
 type DeleteRangeRequest struct {
-	// if the range_end is not given, the request deletes the key.
+	// key is the first key to delete in the range.
 	Key []byte `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"`
-	// if the range_end is given, it deletes the keys in range [key, range_end).
+	// range_end is the key following the last key to delete for the range [key, range_end).
+	// If range_end is not given, the range is defined to contain only the key argument.
+	// If range_end is '\0', the range is all keys greater than or equal to the key argument.
 	RangeEnd []byte `protobuf:"bytes,2,opt,name=range_end,proto3" json:"range_end,omitempty"`
 }
 
@@ -277,7 +286,7 @@ func (*DeleteRangeRequest) ProtoMessage()    {}
 
 type DeleteRangeResponse struct {
 	Header *ResponseHeader `protobuf:"bytes,1,opt,name=header" json:"header,omitempty"`
-	// Deleted is the number of keys that got deleted.
+	// Deleted is the number of keys deleted by the delete range request.
 	Deleted int64 `protobuf:"varint,2,opt,name=deleted,proto3" json:"deleted,omitempty"`
 }
 
@@ -293,6 +302,8 @@ func (m *DeleteRangeResponse) GetHeader() *ResponseHeader {
 }
 
 type RequestUnion struct {
+	// request is a union of request types accepted by a transaction.
+	//
 	// Types that are valid to be assigned to Request:
 	//	*RequestUnion_RequestRange
 	//	*RequestUnion_RequestPut
@@ -420,6 +431,8 @@ func _RequestUnion_OneofUnmarshaler(msg proto.Message, tag, wire int, b *proto.B
 }
 
 type ResponseUnion struct {
+	// response is a union of response types returned by a transaction.
+	//
 	// Types that are valid to be assigned to Response:
 	//	*ResponseUnion_ResponseRange
 	//	*ResponseUnion_ResponsePut
@@ -547,9 +560,11 @@ func _ResponseUnion_OneofUnmarshaler(msg proto.Message, tag, wire int, b *proto.
 }
 
 type Compare struct {
+	// result is logical comparison operation for this comparison.
 	Result Compare_CompareResult `protobuf:"varint,1,opt,name=result,proto3,enum=etcdserverpb.Compare_CompareResult" json:"result,omitempty"`
+	// target is the key-value field to inspect for the comparison.
 	Target Compare_CompareTarget `protobuf:"varint,2,opt,name=target,proto3,enum=etcdserverpb.Compare_CompareTarget" json:"target,omitempty"`
-	// key path
+	// key is the subject key for the comparison operation.
 	Key []byte `protobuf:"bytes,3,opt,name=key,proto3" json:"key,omitempty"`
 	// Types that are valid to be assigned to TargetUnion:
 	//	*Compare_Version
@@ -707,8 +722,15 @@ func _Compare_OneofUnmarshaler(msg proto.Message, tag, wire int, b *proto.Buffer
 // true.
 // 3. A list of database operations called f op. Like t op, but executed if guard evaluates to false.
 type TxnRequest struct {
-	Compare []*Compare      `protobuf:"bytes,1,rep,name=compare" json:"compare,omitempty"`
+	// Compare is a list of predicates representing a conjunction of terms.
+	// If the comparisons succeed, then the success requests will be processed in order,
+	// and the response will contain their respective responses in order.
+	// If the comparisons fail, then the failure requests will be processed in order,
+	// and the response will contain their respective responses in order.
+	Compare []*Compare `protobuf:"bytes,1,rep,name=compare" json:"compare,omitempty"`
+	// success is a list of requests which will be applied when compare evaluates to true.
 	Success []*RequestUnion `protobuf:"bytes,2,rep,name=success" json:"success,omitempty"`
+	// failure is a list of requests which will be applied when compare evaluates to false.
 	Failure []*RequestUnion `protobuf:"bytes,3,rep,name=failure" json:"failure,omitempty"`
 }
 
@@ -738,8 +760,11 @@ func (m *TxnRequest) GetFailure() []*RequestUnion {
 }
 
 type TxnResponse struct {
-	Header    *ResponseHeader  `protobuf:"bytes,1,opt,name=header" json:"header,omitempty"`
-	Succeeded bool             `protobuf:"varint,2,opt,name=succeeded,proto3" json:"succeeded,omitempty"`
+	Header *ResponseHeader `protobuf:"bytes,1,opt,name=header" json:"header,omitempty"`
+	// succeeded is set to true if the compare evaluated to true or false otherwise.
+	Succeeded bool `protobuf:"varint,2,opt,name=succeeded,proto3" json:"succeeded,omitempty"`
+	// responses is a list of responses corresponding to the results from applying
+	// success if succeeded is true or failure if succeeded is false.
 	Responses []*ResponseUnion `protobuf:"bytes,3,rep,name=responses" json:"responses,omitempty"`
 }
 
@@ -761,15 +786,14 @@ func (m *TxnResponse) GetResponses() []*ResponseUnion {
 	return nil
 }
 
-// Compaction compacts the kv store upto the given revision (including).
-// It removes the old versions of a key. It keeps the newest version of
-// the key even if its latest modification revision is smaller than the given
-// revision.
+// CompactionRequest compacts the key-value store upto a given revision. All superseded keys
+// with a revision less than the compaction revision will be removed.
 type CompactionRequest struct {
+	// revision is the key-value store revision for the compation operation.
 	Revision int64 `protobuf:"varint,1,opt,name=revision,proto3" json:"revision,omitempty"`
 	// physical is set so the RPC will wait until the compaction is physically
 	// applied to the local database such that compacted entries are totally
-	// removed from the backing store.
+	// removed from the backend database.
 	Physical bool `protobuf:"varint,2,opt,name=physical,proto3" json:"physical,omitempty"`
 }
 
@@ -801,7 +825,8 @@ func (*HashRequest) ProtoMessage()    {}
 
 type HashResponse struct {
 	Header *ResponseHeader `protobuf:"bytes,1,opt,name=header" json:"header,omitempty"`
-	Hash   uint32          `protobuf:"varint,2,opt,name=hash,proto3" json:"hash,omitempty"`
+	// hash is the hash value computed from the responding member's key-value store.
+	Hash uint32 `protobuf:"varint,2,opt,name=hash,proto3" json:"hash,omitempty"`
 }
 
 func (m *HashResponse) Reset()         { *m = HashResponse{} }
@@ -823,12 +848,12 @@ func (m *SnapshotRequest) String() string { return proto.CompactTextString(m) }
 func (*SnapshotRequest) ProtoMessage()    {}
 
 type SnapshotResponse struct {
-	// header has the current store information. The first header in the snapshot
+	// header has the current key-value store information. The first header in the snapshot
 	// stream indicates the point in time of the snapshot.
 	Header *ResponseHeader `protobuf:"bytes,1,opt,name=header" json:"header,omitempty"`
 	// remaining_bytes is the number of blob bytes to be sent after this message
 	RemainingBytes uint64 `protobuf:"varint,2,opt,name=remaining_bytes,proto3" json:"remaining_bytes,omitempty"`
-	// blob has the next chunk of the snapshot in the snapshot stream.
+	// blob contains the next chunk of the snapshot in the snapshot stream.
 	Blob []byte `protobuf:"bytes,3,opt,name=blob,proto3" json:"blob,omitempty"`
 }
 
@@ -844,6 +869,8 @@ func (m *SnapshotResponse) GetHeader() *ResponseHeader {
 }
 
 type WatchRequest struct {
+	// request_union is a request to either create a new watcher or cancel an existing watcher.
+	//
 	// Types that are valid to be assigned to RequestUnion:
 	//	*WatchRequest_CreateRequest
 	//	*WatchRequest_CancelRequest
@@ -945,17 +972,18 @@ func _WatchRequest_OneofUnmarshaler(msg proto.Message, tag, wire int, b *proto.B
 }
 
 type WatchCreateRequest struct {
-	// the key to be watched
+	// key is the key to register for watching.
 	Key []byte `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"`
-	// if the range_end is given, keys in [key, range_end) are watched
-	// NOTE: only range_end == prefixEnd(key) is accepted now
+	// range_end is the end of the range [key, range_end) to watch. If range_end is not given,
+	// only the key argument is watched. If range_end is equal to '\0', all keys greater than
+	// or equal to the key argument are watched.
 	RangeEnd []byte `protobuf:"bytes,2,opt,name=range_end,proto3" json:"range_end,omitempty"`
-	// start_revision is an optional revision (including) to watch from. No start_revision is "now".
+	// start_revision is an optional revision to watch from (inclusive). No start_revision is "now".
 	StartRevision int64 `protobuf:"varint,3,opt,name=start_revision,proto3" json:"start_revision,omitempty"`
-	// if progress_notify is set, etcd server sends WatchResponse with empty events to the
-	// created watcher when there are no recent events. It is useful when clients want always to be
-	// able to recover a disconnected watcher from a recent known revision.
-	// etcdsever can decide how long it should send a notification based on current load.
+	// progress_notify is set so that the etcd server will periodically send a WatchResponse with
+	// no events to the new watcher if there are no recent events. It is useful when clients
+	// wish to recover a disconnected watcher starting from a recent known revision.
+	// The etcd server may decide how often it will send notifications based on current load.
 	ProgressNotify bool `protobuf:"varint,4,opt,name=progress_notify,proto3" json:"progress_notify,omitempty"`
 }
 
@@ -964,6 +992,7 @@ func (m *WatchCreateRequest) String() string { return proto.CompactTextString(m)
 func (*WatchCreateRequest) ProtoMessage()    {}
 
 type WatchCancelRequest struct {
+	// watch_id is the watcher id to cancel so that no more events are transmitted.
 	WatchId int64 `protobuf:"varint,1,opt,name=watch_id,proto3" json:"watch_id,omitempty"`
 }
 
@@ -973,24 +1002,24 @@ func (*WatchCancelRequest) ProtoMessage()    {}
 
 type WatchResponse struct {
 	Header *ResponseHeader `protobuf:"bytes,1,opt,name=header" json:"header,omitempty"`
-	// watch_id is the ID of the watching the response sent to.
+	// watch_id is the ID of the watcher that corresponds to the response.
 	WatchId int64 `protobuf:"varint,2,opt,name=watch_id,proto3" json:"watch_id,omitempty"`
-	// If the response is for a create watch request, created is set to true.
-	// Client should record the watch_id and prepare for receiving events for
-	// that watching from the same stream.
-	// All events sent to the created watching will attach with the same watch_id.
+	// created is set to true if the response is for a create watch request.
+	// The client should record the watch_id and expect to receive events for
+	// the created watcher from the same stream.
+	// All events sent to the created watcher will attach with the same watch_id.
 	Created bool `protobuf:"varint,3,opt,name=created,proto3" json:"created,omitempty"`
-	// If the response is for a cancel watch request, cancel is set to true.
-	// No further events will be sent to the canceled watching.
+	// canceled is set to true if the response is for a cancel watch request.
+	// No further events will be sent to the canceled watcher.
 	Canceled bool `protobuf:"varint,4,opt,name=canceled,proto3" json:"canceled,omitempty"`
-	// CompactRevision is set to the minimum index if a watching tries to watch
+	// compact_revision is set to the minimum index if a watcher tries to watch
 	// at a compacted index.
 	//
-	// This happens when creating a watching at a compacted revision or the watching cannot
-	// catch up with the progress of the KV.
+	// This happens when creating a watcher at a compacted revision or the watcher cannot
+	// catch up with the progress of the key-value store.
 	//
-	// Client should treat the watching as canceled and should not try to create any
-	// watching with same start_revision again.
+	// The client should treat the watcher as canceled and should not try to create any
+	// watcher with the same start_revision again.
 	CompactRevision int64              `protobuf:"varint,5,opt,name=compact_revision,proto3" json:"compact_revision,omitempty"`
 	Events          []*storagepb.Event `protobuf:"bytes,11,rep,name=events" json:"events,omitempty"`
 }
@@ -1014,9 +1043,9 @@ func (m *WatchResponse) GetEvents() []*storagepb.Event {
 }
 
 type LeaseGrantRequest struct {
-	// advisory ttl in seconds
+	// TTL is the advisory time-to-live in seconds.
 	TTL int64 `protobuf:"varint,1,opt,name=TTL,proto3" json:"TTL,omitempty"`
-	// requested ID to create; 0 lets lessor choose
+	// ID is the requested ID for the lease. If ID is set to 0, the lessor chooses an ID.
 	ID int64 `protobuf:"varint,2,opt,name=ID,proto3" json:"ID,omitempty"`
 }
 
@@ -1026,8 +1055,9 @@ func (*LeaseGrantRequest) ProtoMessage()    {}
 
 type LeaseGrantResponse struct {
 	Header *ResponseHeader `protobuf:"bytes,1,opt,name=header" json:"header,omitempty"`
-	ID     int64           `protobuf:"varint,2,opt,name=ID,proto3" json:"ID,omitempty"`
-	// server decided ttl in second
+	// ID is the lease ID for the granted lease.
+	ID int64 `protobuf:"varint,2,opt,name=ID,proto3" json:"ID,omitempty"`
+	// TTL is the server chosen lease time-to-live in seconds.
 	TTL   int64  `protobuf:"varint,3,opt,name=TTL,proto3" json:"TTL,omitempty"`
 	Error string `protobuf:"bytes,4,opt,name=error,proto3" json:"error,omitempty"`
 }
@@ -1044,6 +1074,7 @@ func (m *LeaseGrantResponse) GetHeader() *ResponseHeader {
 }
 
 type LeaseRevokeRequest struct {
+	// ID is the lease ID to revoke. When the ID is revoked, all associated keys will be deleted.
 	ID int64 `protobuf:"varint,1,opt,name=ID,proto3" json:"ID,omitempty"`
 }
 
@@ -1067,6 +1098,7 @@ func (m *LeaseRevokeResponse) GetHeader() *ResponseHeader {
 }
 
 type LeaseKeepAliveRequest struct {
+	// ID is the lease ID for the lease to keep alive.
 	ID int64 `protobuf:"varint,1,opt,name=ID,proto3" json:"ID,omitempty"`
 }
 
@@ -1076,8 +1108,10 @@ func (*LeaseKeepAliveRequest) ProtoMessage()    {}
 
 type LeaseKeepAliveResponse struct {
 	Header *ResponseHeader `protobuf:"bytes,1,opt,name=header" json:"header,omitempty"`
-	ID     int64           `protobuf:"varint,2,opt,name=ID,proto3" json:"ID,omitempty"`
-	TTL    int64           `protobuf:"varint,3,opt,name=TTL,proto3" json:"TTL,omitempty"`
+	// ID is the lease ID from the keep alive request.
+	ID int64 `protobuf:"varint,2,opt,name=ID,proto3" json:"ID,omitempty"`
+	// TTL is the new time-to-live for the lease.
+	TTL int64 `protobuf:"varint,3,opt,name=TTL,proto3" json:"TTL,omitempty"`
 }
 
 func (m *LeaseKeepAliveResponse) Reset()         { *m = LeaseKeepAliveResponse{} }
@@ -1092,12 +1126,13 @@ func (m *LeaseKeepAliveResponse) GetHeader() *ResponseHeader {
 }
 
 type Member struct {
+	// ID is the member ID for this member.
 	ID uint64 `protobuf:"varint,1,opt,name=ID,proto3" json:"ID,omitempty"`
-	// If the member is not started, name will be an empty string.
-	Name     string   `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
+	// name is the human-readable name of the member. If the member is not started, the name will be an empty string.
+	Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"`
+	// peerURLs is the list of URLs the member exposes to the cluster for communication.
 	PeerURLs []string `protobuf:"bytes,3,rep,name=peerURLs" json:"peerURLs,omitempty"`
-	// If the member is not started, client_URLs will be an zero length
-	// string array.
+	// clientURLs is the list of URLs the member exposes to clients for communication. If the member is not started, clientURLs will be empty.
 	ClientURLs []string `protobuf:"bytes,4,rep,name=clientURLs" json:"clientURLs,omitempty"`
 }
 
@@ -1106,6 +1141,7 @@ func (m *Member) String() string { return proto.CompactTextString(m) }
 func (*Member) ProtoMessage()    {}
 
 type MemberAddRequest struct {
+	// peerURLs is the list of URLs the added member will use to communicate with the cluster.
 	PeerURLs []string `protobuf:"bytes,1,rep,name=peerURLs" json:"peerURLs,omitempty"`
 }
 
@@ -1115,7 +1151,8 @@ func (*MemberAddRequest) ProtoMessage()    {}
 
 type MemberAddResponse struct {
 	Header *ResponseHeader `protobuf:"bytes,1,opt,name=header" json:"header,omitempty"`
-	Member *Member         `protobuf:"bytes,2,opt,name=member" json:"member,omitempty"`
+	// member is the member information for the added member.
+	Member *Member `protobuf:"bytes,2,opt,name=member" json:"member,omitempty"`
 }
 
 func (m *MemberAddResponse) Reset()         { *m = MemberAddResponse{} }
@@ -1137,6 +1174,7 @@ func (m *MemberAddResponse) GetMember() *Member {
 }
 
 type MemberRemoveRequest struct {
+	// ID is the member ID of the member to remove.
 	ID uint64 `protobuf:"varint,1,opt,name=ID,proto3" json:"ID,omitempty"`
 }
 
@@ -1160,7 +1198,9 @@ func (m *MemberRemoveResponse) GetHeader() *ResponseHeader {
 }
 
 type MemberUpdateRequest struct {
-	ID       uint64   `protobuf:"varint,1,opt,name=ID,proto3" json:"ID,omitempty"`
+	// ID is the member ID of the member to update.
+	ID uint64 `protobuf:"varint,1,opt,name=ID,proto3" json:"ID,omitempty"`
+	// peerURLs is the new list of URLs the member will use to communicate with the cluster.
 	PeerURLs []string `protobuf:"bytes,2,rep,name=peerURLs" json:"peerURLs,omitempty"`
 }
 
@@ -1191,8 +1231,9 @@ func (m *MemberListRequest) String() string { return proto.CompactTextString(m)
 func (*MemberListRequest) ProtoMessage()    {}
 
 type MemberListResponse struct {
-	Header  *ResponseHeader `protobuf:"bytes,1,opt,name=header" json:"header,omitempty"`
-	Members []*Member       `protobuf:"bytes,2,rep,name=members" json:"members,omitempty"`
+	Header *ResponseHeader `protobuf:"bytes,1,opt,name=header" json:"header,omitempty"`
+	// members is a list of all members associated with the cluster.
+	Members []*Member `protobuf:"bytes,2,rep,name=members" json:"members,omitempty"`
 }
 
 func (m *MemberListResponse) Reset()         { *m = MemberListResponse{} }
@@ -1236,10 +1277,15 @@ func (m *DefragmentResponse) GetHeader() *ResponseHeader {
 }
 
 type AlarmRequest struct {
+	// action is the kind of alarm request to issue. The action
+	// may GET alarm statuses, ACTIVATE an alarm, or DEACTIVATE a
+	// raised alarm.
 	Action AlarmRequest_AlarmAction `protobuf:"varint,1,opt,name=action,proto3,enum=etcdserverpb.AlarmRequest_AlarmAction" json:"action,omitempty"`
-	// MemberID is the member raising the alarm request
-	MemberID uint64    `protobuf:"varint,2,opt,name=memberID,proto3" json:"memberID,omitempty"`
-	Alarm    AlarmType `protobuf:"varint,3,opt,name=alarm,proto3,enum=etcdserverpb.AlarmType" json:"alarm,omitempty"`
+	// memberID is the ID of the member associated with the alarm. If memberID is 0, the
+	// alarm request covers all members.
+	MemberID uint64 `protobuf:"varint,2,opt,name=memberID,proto3" json:"memberID,omitempty"`
+	// alarm is the type of alarm to consider for this request.
+	Alarm AlarmType `protobuf:"varint,3,opt,name=alarm,proto3,enum=etcdserverpb.AlarmType" json:"alarm,omitempty"`
 }
 
 func (m *AlarmRequest) Reset()         { *m = AlarmRequest{} }
@@ -1247,8 +1293,10 @@ func (m *AlarmRequest) String() string { return proto.CompactTextString(m) }
 func (*AlarmRequest) ProtoMessage()    {}
 
 type AlarmMember struct {
-	MemberID uint64    `protobuf:"varint,1,opt,name=memberID,proto3" json:"memberID,omitempty"`
-	Alarm    AlarmType `protobuf:"varint,2,opt,name=alarm,proto3,enum=etcdserverpb.AlarmType" json:"alarm,omitempty"`
+	// memberID is the ID of the member associated with the raised alarm.
+	MemberID uint64 `protobuf:"varint,1,opt,name=memberID,proto3" json:"memberID,omitempty"`
+	// alarm is the type of alarm which has been raised.
+	Alarm AlarmType `protobuf:"varint,2,opt,name=alarm,proto3,enum=etcdserverpb.AlarmType" json:"alarm,omitempty"`
 }
 
 func (m *AlarmMember) Reset()         { *m = AlarmMember{} }
@@ -1257,7 +1305,8 @@ func (*AlarmMember) ProtoMessage()    {}
 
 type AlarmResponse struct {
 	Header *ResponseHeader `protobuf:"bytes,1,opt,name=header" json:"header,omitempty"`
-	Alarms []*AlarmMember  `protobuf:"bytes,2,rep,name=alarms" json:"alarms,omitempty"`
+	// alarms is a list of alarms associated with the alarm request.
+	Alarms []*AlarmMember `protobuf:"bytes,2,rep,name=alarms" json:"alarms,omitempty"`
 }
 
 func (m *AlarmResponse) Reset()         { *m = AlarmResponse{} }
@@ -1286,12 +1335,17 @@ func (m *StatusRequest) String() string { return proto.CompactTextString(m) }
 func (*StatusRequest) ProtoMessage()    {}
 
 type StatusResponse struct {
-	Header    *ResponseHeader `protobuf:"bytes,1,opt,name=header" json:"header,omitempty"`
-	Version   string          `protobuf:"bytes,2,opt,name=version,proto3" json:"version,omitempty"`
-	DbSize    int64           `protobuf:"varint,3,opt,name=dbSize,proto3" json:"dbSize,omitempty"`
-	Leader    uint64          `protobuf:"varint,4,opt,name=leader,proto3" json:"leader,omitempty"`
-	RaftIndex uint64          `protobuf:"varint,5,opt,name=raftIndex,proto3" json:"raftIndex,omitempty"`
-	RaftTerm  uint64          `protobuf:"varint,6,opt,name=raftTerm,proto3" json:"raftTerm,omitempty"`
+	Header *ResponseHeader `protobuf:"bytes,1,opt,name=header" json:"header,omitempty"`
+	// version is the cluster protocol version used by the responding member.
+	Version string `protobuf:"bytes,2,opt,name=version,proto3" json:"version,omitempty"`
+	// dbSize is the size of the backend database, in bytes, of the responding member.
+	DbSize int64 `protobuf:"varint,3,opt,name=dbSize,proto3" json:"dbSize,omitempty"`
+	// leader is the member ID which the responding member believes is the current leader.
+	Leader uint64 `protobuf:"varint,4,opt,name=leader,proto3" json:"leader,omitempty"`
+	// raftIndex is the current raft index of the responding member.
+	RaftIndex uint64 `protobuf:"varint,5,opt,name=raftIndex,proto3" json:"raftIndex,omitempty"`
+	// raftTerm is the current raft term of the responding member.
+	RaftTerm uint64 `protobuf:"varint,6,opt,name=raftTerm,proto3" json:"raftTerm,omitempty"`
 }
 
 func (m *StatusResponse) Reset()         { *m = StatusResponse{} }
@@ -1343,6 +1397,7 @@ func (m *AuthUserGetRequest) String() string { return proto.CompactTextString(m)
 func (*AuthUserGetRequest) ProtoMessage()    {}
 
 type AuthUserDeleteRequest struct {
+	// name is the name of the user to delete.
 	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
 }
 
@@ -1351,7 +1406,9 @@ func (m *AuthUserDeleteRequest) String() string { return proto.CompactTextString
 func (*AuthUserDeleteRequest) ProtoMessage()    {}
 
 type AuthUserChangePasswordRequest struct {
-	Name     string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
+	// name is the name of the user whose password is being changed.
+	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
+	// password is the new password for the user.
 	Password string `protobuf:"bytes,2,opt,name=password,proto3" json:"password,omitempty"`
 }
 
@@ -1360,7 +1417,9 @@ func (m *AuthUserChangePasswordRequest) String() string { return proto.CompactTe
 func (*AuthUserChangePasswordRequest) ProtoMessage()    {}
 
 type AuthUserGrantRequest struct {
+	// user is the name of the user which should be granted a given role.
 	User string `protobuf:"bytes,1,opt,name=user,proto3" json:"user,omitempty"`
+	// role is the name of the role to grant to the user.
 	Role string `protobuf:"bytes,2,opt,name=role,proto3" json:"role,omitempty"`
 }
 
@@ -1376,6 +1435,7 @@ func (m *AuthUserRevokeRequest) String() string { return proto.CompactTextString
 func (*AuthUserRevokeRequest) ProtoMessage()    {}
 
 type AuthRoleAddRequest struct {
+	// name is the name of the role to add to the authentication system.
 	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
 }
 
@@ -1398,7 +1458,9 @@ func (m *AuthRoleDeleteRequest) String() string { return proto.CompactTextString
 func (*AuthRoleDeleteRequest) ProtoMessage()    {}
 
 type AuthRoleGrantRequest struct {
-	Name string             `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
+	// name is the name of the role which will be granted the permission.
+	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
+	// perm is the permission to grant to the role.
 	Perm *authpb.Permission `protobuf:"bytes,2,opt,name=perm" json:"perm,omitempty"`
 }
 
@@ -1718,23 +1780,24 @@ var _ grpc.ClientConn
 // Client API for KV service
 
 type KVClient interface {
-	// Range gets the keys in the range from the store.
+	// Range gets the keys in the range from the key-value store.
 	Range(ctx context.Context, in *RangeRequest, opts ...grpc.CallOption) (*RangeResponse, error)
-	// Put puts the given key into the store.
-	// A put request increases the revision of the store,
+	// Put puts the given key into the key-value store.
+	// A put request increments the revision of the key-value store
 	// and generates one event in the event history.
 	Put(ctx context.Context, in *PutRequest, opts ...grpc.CallOption) (*PutResponse, error)
-	// Delete deletes the given range from the store.
-	// A delete request increase the revision of the store,
-	// and generates one event in the event history.
+	// Delete deletes the given range from the key-value store.
+	// A delete request increments the revision of the key-value store
+	// and generates a delete event in the event history for every deleted key.
 	DeleteRange(ctx context.Context, in *DeleteRangeRequest, opts ...grpc.CallOption) (*DeleteRangeResponse, error)
-	// Txn processes all the requests in one transaction.
-	// A txn request increases the revision of the store,
-	// and generates events with the same revision in the event history.
+	// Txn processes multiple requests in a single transaction.
+	// A txn request increments the revision of the key-value store
+	// and generates events with the same revision for every completed request.
 	// It is not allowed to modify the same key several times within one txn.
 	Txn(ctx context.Context, in *TxnRequest, opts ...grpc.CallOption) (*TxnResponse, error)
-	// Compact compacts the event history in etcd. User should compact the
-	// event history periodically, or it will grow infinitely.
+	// Compact compacts the event history in the etcd key-value store. The key-value
+	// store should be periodically compacted or the event history will continue to grow
+	// indefinitely.
 	Compact(ctx context.Context, in *CompactionRequest, opts ...grpc.CallOption) (*CompactionResponse, error)
 }
 
@@ -1794,23 +1857,24 @@ func (c *kVClient) Compact(ctx context.Context, in *CompactionRequest, opts ...g
 // Server API for KV service
 
 type KVServer interface {
-	// Range gets the keys in the range from the store.
+	// Range gets the keys in the range from the key-value store.
 	Range(context.Context, *RangeRequest) (*RangeResponse, error)
-	// Put puts the given key into the store.
-	// A put request increases the revision of the store,
+	// Put puts the given key into the key-value store.
+	// A put request increments the revision of the key-value store
 	// and generates one event in the event history.
 	Put(context.Context, *PutRequest) (*PutResponse, error)
-	// Delete deletes the given range from the store.
-	// A delete request increase the revision of the store,
-	// and generates one event in the event history.
+	// Delete deletes the given range from the key-value store.
+	// A delete request increments the revision of the key-value store
+	// and generates a delete event in the event history for every deleted key.
 	DeleteRange(context.Context, *DeleteRangeRequest) (*DeleteRangeResponse, error)
-	// Txn processes all the requests in one transaction.
-	// A txn request increases the revision of the store,
-	// and generates events with the same revision in the event history.
+	// Txn processes multiple requests in a single transaction.
+	// A txn request increments the revision of the key-value store
+	// and generates events with the same revision for every completed request.
 	// It is not allowed to modify the same key several times within one txn.
 	Txn(context.Context, *TxnRequest) (*TxnResponse, error)
-	// Compact compacts the event history in etcd. User should compact the
-	// event history periodically, or it will grow infinitely.
+	// Compact compacts the event history in the etcd key-value store. The key-value
+	// store should be periodically compacted or the event history will continue to grow
+	// indefinitely.
 	Compact(context.Context, *CompactionRequest) (*CompactionResponse, error)
 }
 
@@ -1909,10 +1973,11 @@ var _KV_serviceDesc = grpc.ServiceDesc{
 // Client API for Watch service
 
 type WatchClient interface {
-	// Watch watches the events happening or happened. Both input and output
-	// are stream. One watch rpc can watch for multiple keys or prefixs and
-	// get a stream of events. The whole events history can be watched unless
-	// compacted.
+	// Watch watches for events happening or that have happened. Both input and output
+	// are streams; the input stream is for creating and canceling watchers and the output
+	// stream sends events. One watch RPC can watch on multiple key ranges, streaming events
+	// for several watches at once. The entire event history can be watched starting from the
+	// last compaction revision.
 	Watch(ctx context.Context, opts ...grpc.CallOption) (Watch_WatchClient, error)
 }
 
@@ -1958,10 +2023,11 @@ func (x *watchWatchClient) Recv() (*WatchResponse, error) {
 // Server API for Watch service
 
 type WatchServer interface {
-	// Watch watches the events happening or happened. Both input and output
-	// are stream. One watch rpc can watch for multiple keys or prefixs and
-	// get a stream of events. The whole events history can be watched unless
-	// compacted.
+	// Watch watches for events happening or that have happened. Both input and output
+	// are streams; the input stream is for creating and canceling watchers and the output
+	// stream sends events. One watch RPC can watch on multiple key ranges, streaming events
+	// for several watches at once. The entire event history can be watched starting from the
+	// last compaction revision.
 	Watch(Watch_WatchServer) error
 }
 
@@ -2012,14 +2078,14 @@ var _Watch_serviceDesc = grpc.ServiceDesc{
 // Client API for Lease service
 
 type LeaseClient interface {
-	// LeaseGrant creates a lease. A lease has a TTL. The lease will expire if the
-	// server does not receive a keepAlive within TTL from the lease holder.
-	// All keys attached to the lease will be expired and deleted if the lease expires.
-	// The key expiration generates an event in event history.
+	// LeaseGrant creates a lease which expires if the server does not receive a keepAlive
+	// within a given time to live period. All keys attached to the lease will be expired and
+	// deleted if the lease expires. Each expired key generates a delete event in the event history.
 	LeaseGrant(ctx context.Context, in *LeaseGrantRequest, opts ...grpc.CallOption) (*LeaseGrantResponse, error)
-	// LeaseRevoke revokes a lease. All the key attached to the lease will be expired and deleted.
+	// LeaseRevoke revokes a lease. All keys attached to the lease will expire and be deleted.
 	LeaseRevoke(ctx context.Context, in *LeaseRevokeRequest, opts ...grpc.CallOption) (*LeaseRevokeResponse, error)
-	// KeepAlive keeps the lease alive.
+	// LeaseKeepAlive keeps the lease alive by streaming keep alive requests from the client
+	// to the server and streaming keep alive responses from the server to the client.
 	LeaseKeepAlive(ctx context.Context, opts ...grpc.CallOption) (Lease_LeaseKeepAliveClient, error)
 }
 
@@ -2083,14 +2149,14 @@ func (x *leaseLeaseKeepAliveClient) Recv() (*LeaseKeepAliveResponse, error) {
 // Server API for Lease service
 
 type LeaseServer interface {
-	// LeaseGrant creates a lease. A lease has a TTL. The lease will expire if the
-	// server does not receive a keepAlive within TTL from the lease holder.
-	// All keys attached to the lease will be expired and deleted if the lease expires.
-	// The key expiration generates an event in event history.
+	// LeaseGrant creates a lease which expires if the server does not receive a keepAlive
+	// within a given time to live period. All keys attached to the lease will be expired and
+	// deleted if the lease expires. Each expired key generates a delete event in the event history.
 	LeaseGrant(context.Context, *LeaseGrantRequest) (*LeaseGrantResponse, error)
-	// LeaseRevoke revokes a lease. All the key attached to the lease will be expired and deleted.
+	// LeaseRevoke revokes a lease. All keys attached to the lease will expire and be deleted.
 	LeaseRevoke(context.Context, *LeaseRevokeRequest) (*LeaseRevokeResponse, error)
-	// KeepAlive keeps the lease alive.
+	// LeaseKeepAlive keeps the lease alive by streaming keep alive requests from the client
+	// to the server and streaming keep alive responses from the server to the client.
 	LeaseKeepAlive(Lease_LeaseKeepAliveServer) error
 }
 
@@ -2324,12 +2390,13 @@ type MaintenanceClient interface {
 	Alarm(ctx context.Context, in *AlarmRequest, opts ...grpc.CallOption) (*AlarmResponse, error)
 	// Status gets the status of the member.
 	Status(ctx context.Context, in *StatusRequest, opts ...grpc.CallOption) (*StatusResponse, error)
+	// Defragment defragments a member's backend database to recover storage space.
 	Defragment(ctx context.Context, in *DefragmentRequest, opts ...grpc.CallOption) (*DefragmentResponse, error)
 	// Hash returns the hash of the local KV state for consistency checking purpose.
 	// This is designed for testing; do not use this in production when there
 	// are ongoing transactions.
 	Hash(ctx context.Context, in *HashRequest, opts ...grpc.CallOption) (*HashResponse, error)
-	// Snapshot sends a snapshot of the entire backend
+	// Snapshot sends a snapshot of the entire backend from a member over a stream to a client.
 	Snapshot(ctx context.Context, in *SnapshotRequest, opts ...grpc.CallOption) (Maintenance_SnapshotClient, error)
 }
 
@@ -2416,12 +2483,13 @@ type MaintenanceServer interface {
 	Alarm(context.Context, *AlarmRequest) (*AlarmResponse, error)
 	// Status gets the status of the member.
 	Status(context.Context, *StatusRequest) (*StatusResponse, error)
+	// Defragment defragments a member's backend database to recover storage space.
 	Defragment(context.Context, *DefragmentRequest) (*DefragmentResponse, error)
 	// Hash returns the hash of the local KV state for consistency checking purpose.
 	// This is designed for testing; do not use this in production when there
 	// are ongoing transactions.
 	Hash(context.Context, *HashRequest) (*HashResponse, error)
-	// Snapshot sends a snapshot of the entire backend
+	// Snapshot sends a snapshot of the entire backend from a member over a stream to a client.
 	Snapshot(*SnapshotRequest, Maintenance_SnapshotServer) error
 }
 
@@ -2535,15 +2603,15 @@ type AuthClient interface {
 	AuthEnable(ctx context.Context, in *AuthEnableRequest, opts ...grpc.CallOption) (*AuthEnableResponse, error)
 	// AuthDisable disables authentication.
 	AuthDisable(ctx context.Context, in *AuthDisableRequest, opts ...grpc.CallOption) (*AuthDisableResponse, error)
-	// Authenticate processes authenticate request.
+	// Authenticate processes an authenticate request.
 	Authenticate(ctx context.Context, in *AuthenticateRequest, opts ...grpc.CallOption) (*AuthenticateResponse, error)
 	// UserAdd adds a new user.
 	UserAdd(ctx context.Context, in *AuthUserAddRequest, opts ...grpc.CallOption) (*AuthUserAddResponse, error)
-	// UserGet gets a detailed information of a user or lists entire users.
+	// UserGet gets detailed user information or lists all users.
 	UserGet(ctx context.Context, in *AuthUserGetRequest, opts ...grpc.CallOption) (*AuthUserGetResponse, error)
 	// UserDelete deletes a specified user.
 	UserDelete(ctx context.Context, in *AuthUserDeleteRequest, opts ...grpc.CallOption) (*AuthUserDeleteResponse, error)
-	// UserChangePassword changes password of a specified user.
+	// UserChangePassword changes the password of a specified user.
 	UserChangePassword(ctx context.Context, in *AuthUserChangePasswordRequest, opts ...grpc.CallOption) (*AuthUserChangePasswordResponse, error)
 	// UserGrant grants a role to a specified user.
 	UserGrant(ctx context.Context, in *AuthUserGrantRequest, opts ...grpc.CallOption) (*AuthUserGrantResponse, error)
@@ -2551,7 +2619,7 @@ type AuthClient interface {
 	UserRevoke(ctx context.Context, in *AuthUserRevokeRequest, opts ...grpc.CallOption) (*AuthUserRevokeResponse, error)
 	// RoleAdd adds a new role.
 	RoleAdd(ctx context.Context, in *AuthRoleAddRequest, opts ...grpc.CallOption) (*AuthRoleAddResponse, error)
-	// RoleGet gets a detailed information of a role or lists entire roles.
+	// RoleGet gets detailed role information or lists all roles.
 	RoleGet(ctx context.Context, in *AuthRoleGetRequest, opts ...grpc.CallOption) (*AuthRoleGetResponse, error)
 	// RoleDelete deletes a specified role.
 	RoleDelete(ctx context.Context, in *AuthRoleDeleteRequest, opts ...grpc.CallOption) (*AuthRoleDeleteResponse, error)
@@ -2702,15 +2770,15 @@ type AuthServer interface {
 	AuthEnable(context.Context, *AuthEnableRequest) (*AuthEnableResponse, error)
 	// AuthDisable disables authentication.
 	AuthDisable(context.Context, *AuthDisableRequest) (*AuthDisableResponse, error)
-	// Authenticate processes authenticate request.
+	// Authenticate processes an authenticate request.
 	Authenticate(context.Context, *AuthenticateRequest) (*AuthenticateResponse, error)
 	// UserAdd adds a new user.
 	UserAdd(context.Context, *AuthUserAddRequest) (*AuthUserAddResponse, error)
-	// UserGet gets a detailed information of a user or lists entire users.
+	// UserGet gets detailed user information or lists all users.
 	UserGet(context.Context, *AuthUserGetRequest) (*AuthUserGetResponse, error)
 	// UserDelete deletes a specified user.
 	UserDelete(context.Context, *AuthUserDeleteRequest) (*AuthUserDeleteResponse, error)
-	// UserChangePassword changes password of a specified user.
+	// UserChangePassword changes the password of a specified user.
 	UserChangePassword(context.Context, *AuthUserChangePasswordRequest) (*AuthUserChangePasswordResponse, error)
 	// UserGrant grants a role to a specified user.
 	UserGrant(context.Context, *AuthUserGrantRequest) (*AuthUserGrantResponse, error)
@@ -2718,7 +2786,7 @@ type AuthServer interface {
 	UserRevoke(context.Context, *AuthUserRevokeRequest) (*AuthUserRevokeResponse, error)
 	// RoleAdd adds a new role.
 	RoleAdd(context.Context, *AuthRoleAddRequest) (*AuthRoleAddResponse, error)
-	// RoleGet gets a detailed information of a role or lists entire roles.
+	// RoleGet gets detailed role information or lists all roles.
 	RoleGet(context.Context, *AuthRoleGetRequest) (*AuthRoleGetResponse, error)
 	// RoleDelete deletes a specified role.
 	RoleDelete(context.Context, *AuthRoleDeleteRequest) (*AuthRoleDeleteResponse, error)
diff --git a/etcdserver/etcdserverpb/rpc.proto b/etcdserver/etcdserverpb/rpc.proto
index 6f2b73d18..2904049b1 100644
--- a/etcdserver/etcdserverpb/rpc.proto
+++ b/etcdserver/etcdserverpb/rpc.proto
@@ -9,49 +9,51 @@ option (gogoproto.marshaler_all) = true;
 option (gogoproto.unmarshaler_all) = true;
 
 service KV {
-  // Range gets the keys in the range from the store.
+  // Range gets the keys in the range from the key-value store.
   rpc Range(RangeRequest) returns (RangeResponse) {}
 
-  // Put puts the given key into the store.
-  // A put request increases the revision of the store,
+  // Put puts the given key into the key-value store.
+  // A put request increments the revision of the key-value store
   // and generates one event in the event history.
   rpc Put(PutRequest) returns (PutResponse) {}
 
-  // Delete deletes the given range from the store.
-  // A delete request increase the revision of the store,
-  // and generates one event in the event history.
+  // Delete deletes the given range from the key-value store.
+  // A delete request increments the revision of the key-value store
+  // and generates a delete event in the event history for every deleted key.
   rpc DeleteRange(DeleteRangeRequest) returns (DeleteRangeResponse) {}
 
-  // Txn processes all the requests in one transaction.
-  // A txn request increases the revision of the store,
-  // and generates events with the same revision in the event history.
+  // Txn processes multiple requests in a single transaction.
+  // A txn request increments the revision of the key-value store
+  // and generates events with the same revision for every completed request.
   // It is not allowed to modify the same key several times within one txn.
   rpc Txn(TxnRequest) returns (TxnResponse) {}
 
-  // Compact compacts the event history in etcd. User should compact the
-  // event history periodically, or it will grow infinitely.
+  // Compact compacts the event history in the etcd key-value store. The key-value
+  // store should be periodically compacted or the event history will continue to grow
+  // indefinitely.
   rpc Compact(CompactionRequest) returns (CompactionResponse) {}
 }
 
 service Watch {
-  // Watch watches the events happening or happened. Both input and output
-  // are stream. One watch rpc can watch for multiple keys or prefixs and
-  // get a stream of events. The whole events history can be watched unless
-  // compacted.
+  // Watch watches for events happening or that have happened. Both input and output
+  // are streams; the input stream is for creating and canceling watchers and the output
+  // stream sends events. One watch RPC can watch on multiple key ranges, streaming events
+  // for several watches at once. The entire event history can be watched starting from the
+  // last compaction revision.
   rpc Watch(stream WatchRequest) returns (stream WatchResponse) {}
 }
 
 service Lease {
-  // LeaseGrant creates a lease. A lease has a TTL. The lease will expire if the
-  // server does not receive a keepAlive within TTL from the lease holder.
-  // All keys attached to the lease will be expired and deleted if the lease expires.
-  // The key expiration generates an event in event history.
+  // LeaseGrant creates a lease which expires if the server does not receive a keepAlive
+  // within a given time to live period. All keys attached to the lease will be expired and
+  // deleted if the lease expires. Each expired key generates a delete event in the event history.
   rpc LeaseGrant(LeaseGrantRequest) returns (LeaseGrantResponse) {}
 
-  // LeaseRevoke revokes a lease. All the key attached to the lease will be expired and deleted.
+  // LeaseRevoke revokes a lease. All keys attached to the lease will expire and be deleted.
   rpc LeaseRevoke(LeaseRevokeRequest) returns (LeaseRevokeResponse) {}
 
-  // KeepAlive keeps the lease alive.
+  // LeaseKeepAlive keeps the lease alive by streaming keep alive requests from the client
+  // to the server and streaming keep alive responses from the server to the client.
   rpc LeaseKeepAlive(stream LeaseKeepAliveRequest) returns (stream LeaseKeepAliveResponse) {}
 
   // TODO(xiangli) List all existing Leases?
@@ -79,6 +81,7 @@ service Maintenance {
   // Status gets the status of the member.
   rpc Status(StatusRequest) returns (StatusResponse) {}
 
+  // Defragment defragments a member's backend database to recover storage space.
   rpc Defragment(DefragmentRequest) returns (DefragmentResponse) {}
 
   // Hash returns the hash of the local KV state for consistency checking purpose.
@@ -86,7 +89,7 @@ service Maintenance {
   // are ongoing transactions.
   rpc Hash(HashRequest) returns (HashResponse) {}
 
-  // Snapshot sends a snapshot of the entire backend
+  // Snapshot sends a snapshot of the entire backend from a member over a stream to a client.
   rpc Snapshot(SnapshotRequest) returns (stream SnapshotResponse) {}
 }
 
@@ -97,19 +100,19 @@ service Auth {
   // AuthDisable disables authentication.
   rpc AuthDisable(AuthDisableRequest) returns (AuthDisableResponse) {}
 
-  // Authenticate processes authenticate request.
+  // Authenticate processes an authenticate request.
   rpc Authenticate(AuthenticateRequest) returns (AuthenticateResponse) {}
 
   // UserAdd adds a new user.
   rpc UserAdd(AuthUserAddRequest) returns (AuthUserAddResponse) {}
 
-  // UserGet gets a detailed information of a user or lists entire users.
+  // UserGet gets detailed user information or lists all users.
   rpc UserGet(AuthUserGetRequest) returns (AuthUserGetResponse) {}
 
   // UserDelete deletes a specified user.
   rpc UserDelete(AuthUserDeleteRequest) returns (AuthUserDeleteResponse) {}
 
-  // UserChangePassword changes password of a specified user.
+  // UserChangePassword changes the password of a specified user.
   rpc UserChangePassword(AuthUserChangePasswordRequest) returns (AuthUserChangePasswordResponse) {}
 
   // UserGrant grants a role to a specified user.
@@ -121,7 +124,7 @@ service Auth {
   // RoleAdd adds a new role.
   rpc RoleAdd(AuthRoleAddRequest) returns (AuthRoleAddResponse) {}
 
-  // RoleGet gets a detailed information of a role or lists entire roles.
+  // RoleGet gets detailed role information or lists all roles.
   rpc RoleGet(AuthRoleGetRequest) returns (AuthRoleGetResponse) {}
 
   // RoleDelete deletes a specified role.
@@ -135,11 +138,13 @@ service Auth {
 }
 
 message ResponseHeader {
+  // cluster_id is the ID of the cluster which sent the response.
   uint64 cluster_id = 1;
+  // member_id is the ID of the member which sent the response.
   uint64 member_id = 2;
-  // revision of the store when the request was applied.
+  // revision is the key-value store revision when the request was applied.
   int64 revision = 3;
-  // term of raft when the request was applied.
+  // raft_term is the raft term when the request was applied.
   uint64 raft_term = 4;
 }
 
@@ -157,43 +162,48 @@ message RangeRequest {
 	VALUE = 4;
   }
 
-  // if the range_end is not given, the request returns the key.
+  // key is the first key for the range. If range_end is not given, the request only looks up key.
   bytes key = 1;
-  // if the range_end is given, it gets the keys in range [key, range_end)
-  // if range_end is nonempty, otherwise it returns all keys >= key.
+  // range_end is the upper bound on the requested range [key, range_end).
+  // If range_end is '\0', the range is all keys >= key.
   bytes range_end = 2;
-  // limit the number of keys returned.
+  // limit is a limit on the number of keys returned for the request.
   int64 limit = 3;
-  // range over the store at the given revision.
-  // if revision is less or equal to zero, range over the newest store.
-  // if the revision has been compacted, ErrCompaction will be returned in
-  // response.
+  // revision is the point-in-time of the key-value store to use for the range.
+  // If revision is less or equal to zero, the range is over the newest key-value store.
+  // If the revision has been compacted, ErrCompaction is returned as a response.
   int64 revision = 4;
 
-  // sort_order is the requested order for returned the results
+  // sort_order is the order for returned sorted results.
   SortOrder sort_order = 5;
 
-  // sort_target is the kv field to use for sorting
+  // sort_target is the key-value field to use for sorting.
   SortTarget sort_target = 6;
 
-  // range request is linearizable by default. Linearizable requests has a higher
-  // latency and lower throughput than serializable request.
-  // To reduce latency, serializable can be set. If serializable is set, range request 
-  // will be serializable, but not linearizable with other requests.
-  // Serializable range can be served locally without waiting for other nodes in the cluster.
+  // serializable sets the range request to use serializable member-local reads.
+  // Range requests are linearizable by default; linearizable requests have higher
+  // latency and lower throughput than serializable requests but reflect the current
+  // consensus of the cluster. For better performance, in exchange for possible stale reads,
+  // a serializable range request is served locally without needing to reach consensus
+  // with other nodes in the cluster.
   bool serializable = 7;
 }
 
 message RangeResponse {
   ResponseHeader header = 1;
+  // kvs is the list of key-value pairs matched by the range request.
   repeated storagepb.KeyValue kvs = 2;
   // more indicates if there are more keys to return in the requested range.
   bool more = 3;
 }
 
 message PutRequest {
+  // key is the key, in bytes, to put into the key-value store.
   bytes key = 1;
+  // value is the value, in bytes, to associate with the key in the key-value store.
   bytes value = 2;
+  // lease is the lease ID to associate with the key in the key-value store. A lease
+  // value of 0 indicates no lease.
   int64 lease = 3;
 }
 
@@ -202,19 +212,22 @@ message PutResponse {
 }
 
 message DeleteRangeRequest {
-  // if the range_end is not given, the request deletes the key.
+  // key is the first key to delete in the range.
   bytes key = 1;
-  // if the range_end is given, it deletes the keys in range [key, range_end).
+  // range_end is the key following the last key to delete for the range [key, range_end).
+  // If range_end is not given, the range is defined to contain only the key argument.
+  // If range_end is '\0', the range is all keys greater than or equal to the key argument.
   bytes range_end = 2;
 }
 
 message DeleteRangeResponse {
   ResponseHeader header = 1;
-  // Deleted is the number of keys that got deleted.
+  // Deleted is the number of keys deleted by the delete range request.
   int64 deleted = 2;
 }
 
 message RequestUnion {
+  // request is a union of request types accepted by a transaction.
   oneof request {
     RangeRequest request_range = 1;
     PutRequest request_put = 2;
@@ -223,6 +236,7 @@ message RequestUnion {
 }
 
 message ResponseUnion {
+  // response is a union of response types returned by a transaction.
   oneof response {
     RangeResponse response_range = 1;
     PutResponse response_put = 2;
@@ -242,27 +256,24 @@ message Compare {
     MOD = 2;
     VALUE= 3;
   }
+  // result is logical comparison operation for this comparison.
   CompareResult result = 1;
+  // target is the key-value field to inspect for the comparison.
   CompareTarget target = 2;
-  // key path
+  // key is the subject key for the comparison operation.
   bytes key = 3;
   oneof target_union {
-    // version of the given key
+    // version is the version of the given key
     int64 version = 4;
-    // create revision of the given key
+    // create_revision is the creation revision of the given key
     int64 create_revision = 5;
-    // last modified revision of the given key
+    // mod_revision is the last modified revision of the given key.
     int64 mod_revision = 6;
-    // value of the given key
+    // value is the value of the given key, in bytes.
     bytes value = 7;
   }
 }
 
-// If the comparisons succeed, then the success requests will be processed in order,
-// and the response will contain their respective responses in order.
-// If the comparisons fail, then the failure requests will be processed in order,
-// and the response will contain their respective responses in order.
-
 // From google paxosdb paper:
 // Our implementation hinges around a powerful primitive which we call MultiOp. All other database
 // operations except for iteration are implemented as a single call to MultiOp. A MultiOp is applied atomically
@@ -279,24 +290,35 @@ message Compare {
 // true.
 // 3. A list of database operations called f op. Like t op, but executed if guard evaluates to false.
 message TxnRequest {
+  // Compare is a list of predicates representing a conjunction of terms.
+  // If the comparisons succeed, then the success requests will be processed in order,
+  // and the response will contain their respective responses in order.
+  // If the comparisons fail, then the failure requests will be processed in order,
+  // and the response will contain their respective responses in order.
   repeated Compare compare = 1;
+  // success is a list of requests which will be applied when compare evaluates to true.
   repeated RequestUnion success = 2;
+  // failure is a list of requests which will be applied when compare evaluates to false.
   repeated RequestUnion failure = 3;
 }
 
 message TxnResponse {
   ResponseHeader header = 1;
+  // succeeded is set to true if the compare evaluated to true or false otherwise.
   bool succeeded = 2;
+  // responses is a list of responses corresponding to the results from applying
+  // success if succeeded is true or failure if succeeded is false.
   repeated ResponseUnion responses = 3;
 }
 
-// Compaction compacts the kv store upto a given revision. All superseded keys
+// CompactionRequest compacts the key-value store upto a given revision. All superseded keys
 // with a revision less than the compaction revision will be removed.
 message CompactionRequest {
+  // revision is the key-value store revision for the compation operation. 
   int64 revision = 1;
   // physical is set so the RPC will wait until the compaction is physically
   // applied to the local database such that compacted entries are totally
-  // removed from the backing store.
+  // removed from the backend database.
   bool physical = 2;
 }
 
@@ -309,6 +331,7 @@ message HashRequest {
 
 message HashResponse {
   ResponseHeader header = 1;
+  // hash is the hash value computed from the responding member's key-value store.
   uint32 hash = 2;
 }
 
@@ -316,18 +339,19 @@ message SnapshotRequest {
 }
 
 message SnapshotResponse {
-  // header has the current store information. The first header in the snapshot
+  // header has the current key-value store information. The first header in the snapshot
   // stream indicates the point in time of the snapshot.
   ResponseHeader header = 1;
 
   // remaining_bytes is the number of blob bytes to be sent after this message
   uint64 remaining_bytes = 2;
 
-  // blob has the next chunk of the snapshot in the snapshot stream.
+  // blob contains the next chunk of the snapshot in the snapshot stream.
   bytes blob = 3;
 }
 
 message WatchRequest {
+  // request_union is a request to either create a new watcher or cancel an existing watcher.
   oneof request_union {
     WatchCreateRequest create_request = 1;
     WatchCancelRequest cancel_request = 2;
@@ -335,65 +359,69 @@ message WatchRequest {
 }
 
 message WatchCreateRequest {
-  // the key to be watched
+  // key is the key to register for watching.
   bytes key = 1;
-  // if the range_end is given, keys in [key, range_end) are watched
-  // NOTE: only range_end == prefixEnd(key) is accepted now
+  // range_end is the end of the range [key, range_end) to watch. If range_end is not given,
+  // only the key argument is watched. If range_end is equal to '\0', all keys greater than
+  // or equal to the key argument are watched.
   bytes range_end = 2;
-  // start_revision is an optional revision (including) to watch from. No start_revision is "now".
+  // start_revision is an optional revision to watch from (inclusive). No start_revision is "now".
   int64 start_revision = 3;
-  // if progress_notify is set, etcd server sends WatchResponse with empty events to the 
-  // created watcher when there are no recent events. It is useful when clients want always to be
-  // able to recover a disconnected watcher from a recent known revision.
-  // etcdsever can decide how long it should send a notification based on current load.
+  // progress_notify is set so that the etcd server will periodically send a WatchResponse with
+  // no events to the new watcher if there are no recent events. It is useful when clients
+  // wish to recover a disconnected watcher starting from a recent known revision.
+  // The etcd server may decide how often it will send notifications based on current load.
   bool progress_notify = 4;
 }
 
 message WatchCancelRequest {
+  // watch_id is the watcher id to cancel so that no more events are transmitted.
   int64 watch_id = 1;
 }
 
 message WatchResponse {
   ResponseHeader header = 1;
-  // watch_id is the ID of the watching the response sent to.
+  // watch_id is the ID of the watcher that corresponds to the response.
   int64 watch_id = 2;
-  // If the response is for a create watch request, created is set to true.
-  // Client should record the watch_id and prepare for receiving events for
-  // that watching from the same stream.
-  // All events sent to the created watching will attach with the same watch_id.
+  // created is set to true if the response is for a create watch request.
+  // The client should record the watch_id and expect to receive events for
+  // the created watcher from the same stream.
+  // All events sent to the created watcher will attach with the same watch_id.
   bool created = 3;
-  // If the response is for a cancel watch request, cancel is set to true.
-  // No further events will be sent to the canceled watching.
+  // canceled is set to true if the response is for a cancel watch request.
+  // No further events will be sent to the canceled watcher.
   bool canceled = 4;
-  // CompactRevision is set to the minimum index if a watching tries to watch
+  // compact_revision is set to the minimum index if a watcher tries to watch
   // at a compacted index.
   //
-  // This happens when creating a watching at a compacted revision or the watching cannot
-  // catch up with the progress of the KV.
+  // This happens when creating a watcher at a compacted revision or the watcher cannot
+  // catch up with the progress of the key-value store. 
   //
-  // Client should treat the watching as canceled and should not try to create any
-  // watching with same start_revision again.
+  // The client should treat the watcher as canceled and should not try to create any
+  // watcher with the same start_revision again.
   int64 compact_revision  = 5;
 
   repeated storagepb.Event events = 11;
 }
 
 message LeaseGrantRequest {
-  // advisory ttl in seconds
+  // TTL is the advisory time-to-live in seconds.
   int64 TTL = 1;
-  // requested ID to create; 0 lets lessor choose
+  // ID is the requested ID for the lease. If ID is set to 0, the lessor chooses an ID.
   int64 ID = 2;
 }
 
 message LeaseGrantResponse {
   ResponseHeader header = 1;
+  // ID is the lease ID for the granted lease.
   int64 ID = 2;
-  // server decided ttl in second
+  // TTL is the server chosen lease time-to-live in seconds.
   int64 TTL = 3;
   string error = 4;
 }
 
 message LeaseRevokeRequest {
+  // ID is the lease ID to revoke. When the ID is revoked, all associated keys will be deleted.
   int64 ID = 1;
 }
 
@@ -402,35 +430,42 @@ message LeaseRevokeResponse {
 }
 
 message LeaseKeepAliveRequest {
+  // ID is the lease ID for the lease to keep alive.
   int64 ID = 1;
 }
 
 message LeaseKeepAliveResponse {
   ResponseHeader header = 1;
+  // ID is the lease ID from the keep alive request.
   int64 ID = 2;
+  // TTL is the new time-to-live for the lease.
   int64 TTL = 3;
 }
 
 message Member {
+  // ID is the member ID for this member.
   uint64 ID = 1;
-  // If the member is not started, name will be an empty string.
+  // name is the human-readable name of the member. If the member is not started, the name will be an empty string.
   string name = 2;
+  // peerURLs is the list of URLs the member exposes to the cluster for communication.
   repeated string peerURLs = 3;
-  // If the member is not started, client_URLs will be an zero length
-  // string array.
+  // clientURLs is the list of URLs the member exposes to clients for communication. If the member is not started, clientURLs will be empty.
   repeated string clientURLs = 4;
 }
 
 message MemberAddRequest {
+  // peerURLs is the list of URLs the added member will use to communicate with the cluster.
   repeated string peerURLs = 1;
 }
 
 message MemberAddResponse {
   ResponseHeader header = 1;
+  // member is the member information for the added member.
   Member member = 2;
 }
 
 message MemberRemoveRequest {
+  // ID is the member ID of the member to remove.
   uint64 ID = 1;
 }
 
@@ -439,7 +474,9 @@ message MemberRemoveResponse {
 }
 
 message MemberUpdateRequest {
+  // ID is the member ID of the member to update.
   uint64 ID = 1;
+  // peerURLs is the new list of URLs the member will use to communicate with the cluster.
   repeated string peerURLs = 2;
 }
 
@@ -452,6 +489,7 @@ message MemberListRequest {
 
 message MemberListResponse {
   ResponseHeader header = 1;
+  // members is a list of all members associated with the cluster.
   repeated Member members = 2;
 }
 
@@ -464,7 +502,7 @@ message DefragmentResponse {
 
 enum AlarmType {
 	NONE = 0; // default, used to query if any alarm is active
-	NOSPACE = 1;
+	NOSPACE = 1; // space quota is exhausted
 }
 
 message AlarmRequest {
@@ -473,19 +511,27 @@ message AlarmRequest {
 	ACTIVATE = 1;
 	DEACTIVATE = 2;
   }
+  // action is the kind of alarm request to issue. The action
+  // may GET alarm statuses, ACTIVATE an alarm, or DEACTIVATE a
+  // raised alarm.
   AlarmAction action = 1;
-  // MemberID is the member raising the alarm request
+  // memberID is the ID of the member associated with the alarm. If memberID is 0, the
+  // alarm request covers all members.
   uint64 memberID = 2;
+  // alarm is the type of alarm to consider for this request.
   AlarmType alarm = 3;
 }
 
 message AlarmMember {
-	uint64	memberID = 1;
-	AlarmType alarm = 2;
+  // memberID is the ID of the member associated with the raised alarm.
+  uint64 memberID = 1;
+  // alarm is the type of alarm which has been raised.
+  AlarmType alarm = 2;
 }
 
 message AlarmResponse {
   ResponseHeader header = 1;
+  // alarms is a list of alarms associated with the alarm request.
   repeated AlarmMember alarms = 2;
 }
 
@@ -494,10 +540,15 @@ message StatusRequest {
 
 message StatusResponse {
   ResponseHeader header = 1;
+  // version is the cluster protocol version used by the responding member.
   string version = 2;
+  // dbSize is the size of the backend database, in bytes, of the responding member.
   int64 dbSize = 3;
+  // leader is the member ID which the responding member believes is the current leader.
   uint64 leader = 4;
+  // raftIndex is the current raft index of the responding member.
   uint64 raftIndex = 5;
+  // raftTerm is the current raft term of the responding member.
   uint64 raftTerm = 6;
 }
 
@@ -519,16 +570,21 @@ message AuthUserGetRequest {
 }
 
 message AuthUserDeleteRequest {
+  // name is the name of the user to delete.
   string name = 1;
 }
 
 message AuthUserChangePasswordRequest {
+  // name is the name of the user whose password is being changed.
   string name = 1;
+  // password is the new password for the user.
   string password = 2;
 }
 
 message AuthUserGrantRequest {
+  // user is the name of the user which should be granted a given role.
   string user = 1;
+  // role is the name of the role to grant to the user.
   string role = 2;
 }
 
@@ -536,6 +592,7 @@ message AuthUserRevokeRequest {
 }
 
 message AuthRoleAddRequest {
+  // name is the name of the role to add to the authentication system.
   string name = 1;
 }
 
@@ -546,7 +603,9 @@ message AuthRoleDeleteRequest {
 }
 
 message AuthRoleGrantRequest {
+  // name is the name of the role which will be granted the permission.
   string name = 1;
+  // perm is the permission to grant to the role.
   authpb.Permission perm = 2;
 }
 
diff --git a/storage/storagepb/kv.pb.go b/storage/storagepb/kv.pb.go
index 2987b9be6..13f64ed46 100644
--- a/storage/storagepb/kv.pb.go
+++ b/storage/storagepb/kv.pb.go
@@ -53,6 +53,7 @@ func (x Event_EventType) String() string {
 }
 
 type KeyValue struct {
+	// key is the key in bytes. An empty key is not allowed.
 	Key []byte `protobuf:"bytes,1,opt,name=key,proto3" json:"key,omitempty"`
 	// create_revision is the revision of last creation on this key.
 	CreateRevision int64 `protobuf:"varint,2,opt,name=create_revision,proto3" json:"create_revision,omitempty"`
@@ -61,10 +62,12 @@ type KeyValue struct {
 	// version is the version of the key. A deletion resets
 	// the version to zero and any modification of the key
 	// increases its version.
-	Version int64  `protobuf:"varint,4,opt,name=version,proto3" json:"version,omitempty"`
-	Value   []byte `protobuf:"bytes,5,opt,name=value,proto3" json:"value,omitempty"`
+	Version int64 `protobuf:"varint,4,opt,name=version,proto3" json:"version,omitempty"`
+	// value is the value held by the key, in bytes.
+	Value []byte `protobuf:"bytes,5,opt,name=value,proto3" json:"value,omitempty"`
 	// lease is the ID of the lease that attached to key.
 	// When the attached lease expires, the key will be deleted.
+	// If lease is 0, then no lease is attached to the key.
 	Lease int64 `protobuf:"varint,6,opt,name=lease,proto3" json:"lease,omitempty"`
 }
 
@@ -73,7 +76,11 @@ func (m *KeyValue) String() string { return proto.CompactTextString(m) }
 func (*KeyValue) ProtoMessage()    {}
 
 type Event struct {
+	// type is the kind of event. If type is a PUT, it indicates
+	// new data has been stored to the key. If type is a DELETE,
+	// it indicates the key was deleted.
 	Type Event_EventType `protobuf:"varint,1,opt,name=type,proto3,enum=storagepb.Event_EventType" json:"type,omitempty"`
+	// kv holds the KeyValue for the event.
 	// A PUT event contains current kv pair.
 	// A PUT event with kv.Version=1 indicates the creation of a key.
 	// A DELETE/EXPIRE event contains the deleted key with
diff --git a/storage/storagepb/kv.proto b/storage/storagepb/kv.proto
index bfd48553c..7e5e50ae6 100644
--- a/storage/storagepb/kv.proto
+++ b/storage/storagepb/kv.proto
@@ -10,6 +10,7 @@ option (gogoproto.goproto_getters_all) = false;
 option (gogoproto.goproto_enum_prefix_all) = false;
 
 message KeyValue {
+  // key is the key in bytes. An empty key is not allowed.
   bytes key = 1;
   // create_revision is the revision of last creation on this key.
   int64 create_revision = 2;
@@ -19,9 +20,11 @@ message KeyValue {
   // the version to zero and any modification of the key
   // increases its version.
   int64 version = 4;
+  // value is the value held by the key, in bytes.
   bytes value = 5;
   // lease is the ID of the lease that attached to key.
   // When the attached lease expires, the key will be deleted.
+  // If lease is 0, then no lease is attached to the key.
   int64 lease = 6;
 }
 
@@ -31,7 +34,11 @@ message Event {
     DELETE = 1;
     EXPIRE = 2;
   }
+  // type is the kind of event. If type is a PUT, it indicates
+  // new data has been stored to the key. If type is a DELETE,
+  // it indicates the key was deleted.
   EventType type = 1;
+  // kv holds the KeyValue for the event.
   // A PUT event contains current kv pair.
   // A PUT event with kv.Version=1 indicates the creation of a key.
   // A DELETE/EXPIRE event contains the deleted key with