[IMPROVED] Clarify MessagesContext.Next() doc (#1951)

Signed-off-by: Piotr Piotrowski <[email protected]>

Author: piotrpio

jetstream/pull.go

@@ -33,12 +33,11 @@ type (
 	// MessagesContext supports iterating over a messages on a stream.
 	// It is returned by [Consumer.Messages] method.
 	MessagesContext interface {
-		// Next retrieves next message on a stream. It will block until the next
-		// message is available. If the context is canceled, Next will return
-		// ErrMsgIteratorClosed error. An optional timeout or context can be
-		// provided using NextOpt options. If none are provided, Next will block
-		// indefinitely until a message is available, iterator is closed or a
-		// heartbeat error occurs.
+		// Next retrieves next message on a stream. If MessagesContext is closed
+		// (either stopped or drained), Next will return ErrMsgIteratorClosed
+		// error. An optional timeout or context can be provided using NextOpt
+		// options. If none are provided, Next will block indefinitely until a
+		// message is available, iterator is closed or a heartbeat error occurs.
 		Next(opts ...NextOpt) (Msg, error)
 
 		// Stop unsubscribes from the stream and cancels subscription. Calling
@@ -589,9 +588,11 @@ var (
 	errDisconnected = errors.New("disconnected")
 )
 
-// Next retrieves next message on a stream. It will block until the next
-// message is available. If the context is canceled, Next will return
-// ErrMsgIteratorClosed error.
+// Next retrieves next message on a stream. If MessagesContext is closed
+// (either stopped or drained), Next will return ErrMsgIteratorClosed
+// error. An optional timeout or context can be provided using NextOpt
+// options. If none are provided, Next will block indefinitely until a
+// message is available, iterator is closed or a heartbeat error occurs.
 func (s *pullSubscription) Next(opts ...NextOpt) (Msg, error) {
 	var nextOpts nextOpts
 	for _, opt := range opts {