documentation: clarify SendMsg documentation (#2171)

documentation: clarify SendMsg documentation

Relevant issue: #2159

stream.go

@@ -59,15 +59,25 @@ type StreamDesc struct {
 type Stream interface {
 	// Context returns the context for this stream.
 	Context() context.Context
-	// SendMsg blocks until it sends m, the stream is done or the stream
+	// SendMsg is generally called by generated code. On error, SendMsg aborts
-	// breaks.
+	// the stream and returns an RPC status on the client side. On the server
-	// On error, it aborts the stream and returns an RPC status on client
+	// side, it simply returns the error to the caller.
-	// side. On server side, it simply returns the error to the caller.
+	//
-	// SendMsg is called by generated code. Also Users can call SendMsg
+	// SendMsg blocks until:
-	// directly when it is really needed in their use cases.
+	//   - It schedules m with the transport, or
-	// It's safe to have a goroutine calling SendMsg and another goroutine calling
+	//   - The stream is done, or
-	// recvMsg on the same stream at the same time.
+	//   - The stream breaks.
-	// But it is not safe to call SendMsg on the same stream in different goroutines.
+	//
+	// SendMsg does not wait for an ack. An untimely stream closure
+	// can result in any buffered messages along the way (including
+	// those in the client-side buffer that comes with gRPC by default)
+	// being lost. To ensure delivery, users must call RecvMsg until
+	// receiving an EOF before closing the stream.
+	//
+	// It's safe to have a goroutine calling SendMsg and another
+	// goroutine calling RecvMsg on the same stream at the same
+	// time. It is not safe to call SendMsg on the same stream
+	// in different goroutines.
 	SendMsg(m interface{}) error
 	// RecvMsg blocks until it receives a message or the stream is
 	// done. On client side, it returns io.EOF when the stream is done. On