Merge pull request #1221 from adelez/doc_fixit

Fix doc

clientconn.go

@@ -56,8 +56,7 @@ var (
 	ErrClientConnClosing = errors.New("grpc: the client connection is closing")
 	// ErrClientConnTimeout indicates that the ClientConn cannot establish the
 	// underlying connections within the specified timeout.
-	// DEPRECATED: Please use context.DeadlineExceeded instead. This error will be
+	// DEPRECATED: Please use context.DeadlineExceeded instead.
-	// removed in Q1 2017.
 	ErrClientConnTimeout = errors.New("grpc: timed out when dialing")
 
 	// errNoTransportSecurity indicates that there is no transport security
@@ -204,7 +203,7 @@ func WithTransportCredentials(creds credentials.TransportCredentials) DialOption
 }
 
 // WithPerRPCCredentials returns a DialOption which sets
-// credentials which will place auth state on each outbound RPC.
+// credentials and places auth state on each outbound RPC.
 func WithPerRPCCredentials(creds credentials.PerRPCCredentials) DialOption {
 	return func(o *dialOptions) {
 		o.copts.PerRPCCredentials = append(o.copts.PerRPCCredentials, creds)
@@ -241,7 +240,7 @@ func WithStatsHandler(h stats.Handler) DialOption {
 	}
 }
 
-// FailOnNonTempDialError returns a DialOption that specified if gRPC fails on non-temporary dial errors.
+// FailOnNonTempDialError returns a DialOption that specifies if gRPC fails on non-temporary dial errors.
 // If f is true, and dialer returns a non-temporary error, gRPC will fail the connection to the network
 // address and won't try to reconnect.
 // The default value of FailOnNonTempDialError is false.
@@ -295,10 +294,9 @@ func Dial(target string, opts ...DialOption) (*ClientConn, error) {
 }
 
 // DialContext creates a client connection to the given target. ctx can be used to
-// cancel or expire the pending connecting. Once this function returns, the
+// cancel or expire the pending connection. Once this function returns, the
 // cancellation and expiration of ctx will be noop. Users should call ClientConn.Close
 // to terminate all the pending operations after this function returns.
-// This is the EXPERIMENTAL API.
 func DialContext(ctx context.Context, target string, opts ...DialOption) (conn *ClientConn, err error) {
 	cc := &ClientConn{
 		target: target,

credentials/credentials.go

@@ -196,14 +196,14 @@ func NewTLS(c *tls.Config) TransportCredentials {
 	return tc
 }
 
-// NewClientTLSFromCert constructs a TLS from the input certificate for client.
+// NewClientTLSFromCert constructs TLS credentials from the input certificate for client.
 // serverNameOverride is for testing only. If set to a non empty string,
 // it will override the virtual host name of authority (e.g. :authority header field) in requests.
 func NewClientTLSFromCert(cp *x509.CertPool, serverNameOverride string) TransportCredentials {
 	return NewTLS(&tls.Config{ServerName: serverNameOverride, RootCAs: cp})
 }
 
-// NewClientTLSFromFile constructs a TLS from the input certificate file for client.
+// NewClientTLSFromFile constructs TLS credentials from the input certificate file for client.
 // serverNameOverride is for testing only. If set to a non empty string,
 // it will override the virtual host name of authority (e.g. :authority header field) in requests.
 func NewClientTLSFromFile(certFile, serverNameOverride string) (TransportCredentials, error) {
@@ -218,12 +218,12 @@ func NewClientTLSFromFile(certFile, serverNameOverride string) (TransportCredent
 	return NewTLS(&tls.Config{ServerName: serverNameOverride, RootCAs: cp}), nil
 }
 
-// NewServerTLSFromCert constructs a TLS from the input certificate for server.
+// NewServerTLSFromCert constructs TLS credentials from the input certificate for server.
 func NewServerTLSFromCert(cert *tls.Certificate) TransportCredentials {
 	return NewTLS(&tls.Config{Certificates: []tls.Certificate{*cert}})
 }
 
-// NewServerTLSFromFile constructs a TLS from the input certificate file and key
+// NewServerTLSFromFile constructs TLS credentials from the input certificate file and key
 // file for server.
 func NewServerTLSFromFile(certFile, keyFile string) (TransportCredentials, error) {
 	cert, err := tls.LoadX509KeyPair(certFile, keyFile)

grpclb.go

@@ -96,8 +96,8 @@ const (
 	GRPCLB
 )
 
-// AddrMetadataGRPCLB contains the information the name resolution for grpclb should provide. The
+// AddrMetadataGRPCLB contains the information the name resolver for grpclb should provide. The
-// name resolver used by grpclb balancer is required to provide this type of metadata in
+// name resolver used by the grpclb balancer is required to provide this type of metadata in
 // its address updates.
 type AddrMetadataGRPCLB struct {
 	// AddrType is the type of server (grpc load balancer or backend).

interceptor.go

@@ -42,15 +42,15 @@ type UnaryInvoker func(ctx context.Context, method string, req, reply interface{
 
 // UnaryClientInterceptor intercepts the execution of a unary RPC on the client. invoker is the handler to complete the RPC
 // and it is the responsibility of the interceptor to call it.
-// This is the EXPERIMENTAL API.
+// This is an EXPERIMENTAL API.
 type UnaryClientInterceptor func(ctx context.Context, method string, req, reply interface{}, cc *ClientConn, invoker UnaryInvoker, opts ...CallOption) error
 
 // Streamer is called by StreamClientInterceptor to create a ClientStream.
 type Streamer func(ctx context.Context, desc *StreamDesc, cc *ClientConn, method string, opts ...CallOption) (ClientStream, error)
 
 // StreamClientInterceptor intercepts the creation of ClientStream. It may return a custom ClientStream to intercept all I/O
-// operations. streamer is the handlder to create a ClientStream and it is the responsibility of the interceptor to call it.
+// operations. streamer is the handler to create a ClientStream and it is the responsibility of the interceptor to call it.
-// This is the EXPERIMENTAL API.
+// This is an EXPERIMENTAL API.
 type StreamClientInterceptor func(ctx context.Context, desc *StreamDesc, cc *ClientConn, method string, streamer Streamer, opts ...CallOption) (ClientStream, error)
 
 // UnaryServerInfo consists of various information about a unary RPC on

keepalive/keepalive.go

@@ -39,8 +39,8 @@ import (
 )
 
 // ClientParameters is used to set keepalive parameters on the client-side.
-// These configure how the client will actively probe to notice when a connection broken
+// These configure how the client will actively probe to notice when a connection is broken
-// and to cause activity so intermediaries are aware the connection is still in use.
+// and send pings so intermediaries will be aware of the liveness of the connection.
 // Make sure these parameters are set in coordination with the keepalive policy on the server,
 // as incompatible settings can result in closing of connection.
 type ClientParameters struct {

metadata/metadata.go

@@ -51,7 +51,7 @@ func DecodeKeyValue(k, v string) (string, string, error) {
 // two convenience functions New and Pairs to generate MD.
 type MD map[string][]string
 
-// New creates a MD from given key-value map.
+// New creates an MD from a given key-value map.
 // Keys are automatically converted to lowercase.
 func New(m map[string]string) MD {
 	md := MD{}
@@ -91,9 +91,9 @@ func (md MD) Copy() MD {
 	return Join(md)
 }
 
-// Join joins any number of MDs into a single MD.
+// Join joins any number of mds into a single MD.
 // The order of values for each key is determined by the order in which
-// the MDs containing those values are presented to Join.
+// the mds containing those values are presented to Join.
 func Join(mds ...MD) MD {
 	out := MD{}
 	for _, md := range mds {
@@ -127,17 +127,17 @@ func FromContext(ctx context.Context) (md MD, ok bool) {
 	return FromIncomingContext(ctx)
 }
 
-// FromIncomingContext returns the incoming MD in ctx if it exists.  The
+// FromIncomingContext returns the incoming metadata in ctx if it exists.  The
-// returned md should be immutable, writing to it may cause races.
+// returned MD should not be modified. Writing to it may cause races.
-// Modification should be made to the copies of the returned md.
+// Modification should be made to copies of the returned MD.
 func FromIncomingContext(ctx context.Context) (md MD, ok bool) {
 	md, ok = ctx.Value(mdIncomingKey{}).(MD)
 	return
 }
 
-// FromOutgoingContext returns the outgoing MD in ctx if it exists.  The
+// FromOutgoingContext returns the outgoing metadata in ctx if it exists.  The
-// returned md should be immutable, writing to it may cause races.
+// returned MD should not be modified. Writing to it may cause races.
-// Modification should be made to the copies of the returned md.
+// Modification should be made to the copies of the returned MD.
 func FromOutgoingContext(ctx context.Context) (md MD, ok bool) {
 	md, ok = ctx.Value(mdOutgoingKey{}).(MD)
 	return

peer/peer.go

@@ -42,7 +42,8 @@ import (
 	"google.golang.org/grpc/credentials"
 )
 
-// Peer contains the information of the peer for an RPC.
+// Peer contains the information of the peer for an RPC, such as the address
+// and authentication information.
 type Peer struct {
 	// Addr is the peer address.
 	Addr net.Addr

rpc_util.go

@@ -173,7 +173,8 @@ func Peer(peer *peer.Peer) CallOption {
 // immediately. Otherwise, the RPC client will block the call until a
 // connection is available (or the call is canceled or times out) and will retry
 // the call if it fails due to a transient error. Please refer to
-// https://github.com/grpc/grpc/blob/master/doc/fail_fast.md. Note: failFast is default to true.
+// https://github.com/grpc/grpc/blob/master/doc/wait-for-ready.md.
+// Note: failFast is default to true.
 func FailFast(failFast bool) CallOption {
 	return beforeCall(func(c *callInfo) error {
 		c.failFast = failFast

server.go

@@ -125,7 +125,7 @@ type options struct {
 
 var defaultMaxMsgSize = 1024 * 1024 * 4 // use 4MB as the default message size limit
 
-// A ServerOption sets options.
+// A ServerOption sets options such as credentials, codec and keepalive parameters, etc.
 type ServerOption func(*options)
 
 // KeepaliveParams returns a ServerOption that sets keepalive and max-age parameters for the server.
@@ -229,7 +229,7 @@ func StatsHandler(h stats.Handler) ServerOption {
 
 // UnknownServiceHandler returns a ServerOption that allows for adding a custom
 // unknown service handler. The provided method is a bidi-streaming RPC service
-// handler that will be invoked instead of returning the the "unimplemented" gRPC
+// handler that will be invoked instead of returning the "unimplemented" gRPC
 // error whenever a request is received for an unregistered service or method.
 // The handling function has full access to the Context of the request and the
 // stream, and the invocation passes through interceptors.
@@ -288,8 +288,8 @@ func (s *Server) errorf(format string, a ...interface{}) {
 	}
 }
 
-// RegisterService register a service and its implementation to the gRPC
+// RegisterService registers a service and its implementation to the gRPC
-// server. Called from the IDL generated code. This must be called before
+// server. It is called from the IDL generated code. This must be called before
 // invoking Serve.
 func (s *Server) RegisterService(sd *ServiceDesc, ss interface{}) {
 	ht := reflect.TypeOf(sd.HandlerType).Elem()
@@ -334,7 +334,7 @@ type MethodInfo struct {
 	IsServerStream bool
 }
 
-// ServiceInfo contains unary RPC method info, streaming RPC methid info and metadata for a service.
+// ServiceInfo contains unary RPC method info, streaming RPC method info and metadata for a service.
 type ServiceInfo struct {
 	Methods []MethodInfo
 	// Metadata is the metadata specified in ServiceDesc when registering service.
@@ -1007,8 +1007,9 @@ func (s *Server) Stop() {
 	s.mu.Unlock()
 }
 
-// GracefulStop stops the gRPC server gracefully. It stops the server to accept new
+// GracefulStop stops the gRPC server gracefully. It stops the server from
-// connections and RPCs and blocks until all the pending RPCs are finished.
+// accepting new connections and RPCs and blocks until all the pending RPCs are
+// finished.
 func (s *Server) GracefulStop() {
 	s.mu.Lock()
 	defer s.mu.Unlock()

stats/stats.go

@@ -49,7 +49,7 @@ type RPCStats interface {
 }
 
 // Begin contains stats when an RPC begins.
-// FailFast are only valid if Client is true.
+// FailFast is only valid if this Begin is from client side.
 type Begin struct {
 	// Client is true if this Begin is from client side.
 	Client bool
@@ -59,7 +59,7 @@ type Begin struct {
 	FailFast bool
 }
 
-// IsClient indicates if this is from client side.
+// IsClient indicates if the stats information is from client side.
 func (s *Begin) IsClient() bool { return s.Client }
 
 func (s *Begin) isRPCStats() {}
@@ -80,7 +80,7 @@ type InPayload struct {
 	RecvTime time.Time
 }
 
-// IsClient indicates if this is from client side.
+// IsClient indicates if the stats information is from client side.
 func (s *InPayload) IsClient() bool { return s.Client }
 
 func (s *InPayload) isRPCStats() {}
@@ -103,7 +103,7 @@ type InHeader struct {
 	Compression string
 }
 
-// IsClient indicates if this is from client side.
+// IsClient indicates if the stats information is from client side.
 func (s *InHeader) IsClient() bool { return s.Client }
 
 func (s *InHeader) isRPCStats() {}
@@ -116,7 +116,7 @@ type InTrailer struct {
 	WireLength int
 }
 
-// IsClient indicates if this is from client side.
+// IsClient indicates if the stats information is from client side.
 func (s *InTrailer) IsClient() bool { return s.Client }
 
 func (s *InTrailer) isRPCStats() {}
@@ -137,7 +137,7 @@ type OutPayload struct {
 	SentTime time.Time
 }
 
-// IsClient indicates if this is from client side.
+// IsClient indicates if this stats information is from client side.
 func (s *OutPayload) IsClient() bool { return s.Client }
 
 func (s *OutPayload) isRPCStats() {}
@@ -160,7 +160,7 @@ type OutHeader struct {
 	Compression string
 }
 
-// IsClient indicates if this is from client side.
+// IsClient indicates if this stats information is from client side.
 func (s *OutHeader) IsClient() bool { return s.Client }
 
 func (s *OutHeader) isRPCStats() {}
@@ -173,7 +173,7 @@ type OutTrailer struct {
 	WireLength int
 }
 
-// IsClient indicates if this is from client side.
+// IsClient indicates if this stats information is from client side.
 func (s *OutTrailer) IsClient() bool { return s.Client }
 
 func (s *OutTrailer) isRPCStats() {}