NoWait documentation (#1256)

Author: roeschter

src/main/java/io/nats/client/FetchConsumeOptions.java

@@ -96,6 +96,7 @@ public Builder max(int maxBytes, int maxMessages) {
 
         /**
          * Set no wait to true
+         * When no wait is true, the fetch will return immediately with as many messages as are available. Between zero and the maximum configured.
          * @return the builder
          */
         @Override
@@ -106,7 +107,9 @@ public Builder noWait() {
         }
 
         /**
-         * Set no wait to true with an expiration, special behavior.
+         * Set no wait to true with an expiration. This is the common configuration to receive messages as soon as they arrive in the stream without excessive pulling.
+         * When no wait is true with expire, the fetch will return immediately with as many messages as are available, but at least one message. Between one and the maximum configured.
+         * When no message is available it will wait for new messages to arrive till it expires.
          * @param expiresInMillis the expiration time in milliseconds
          * @return the builder
          */

src/main/java/io/nats/client/JetStreamSubscription.java

@@ -53,7 +53,7 @@ public interface JetStreamSubscription extends Subscription {
 
     /**
      * Initiate pull in noWait mode with the specified batch size.
-     *
+     * The fetch will return immediately with as many messages as are available. Between zero and the maximum configured.
      * ! Pull subscriptions only. Push subscription will throw IllegalStateException
      * ! Primitive API for ADVANCED use only, officially not supported. Prefer fetch, iterate or reader.
      *
@@ -64,6 +64,8 @@ public interface JetStreamSubscription extends Subscription {
 
     /**
      * Initiate pull in noWait mode with the specified batch size.
+     * The fetch will return immediately with as many messages as are available, but at least one message. Between one and the maximum configured.
+     * When no message is available it will wait for new messages to arrive till it expires.
      * ! Pull subscriptions only. Push subscription will throw IllegalStateException
      * ! Primitive API for ADVANCED use only, officially not supported. Prefer fetch, iterate or reader.
      *
@@ -75,6 +77,8 @@ public interface JetStreamSubscription extends Subscription {
 
     /**
      * Initiate pull in noWait mode with the specified batch size.
+     * The fetch will return immediately with as many messages as are available, but at least one message. Between one and the maximum configured.
+     * When no message is available it will wait for new messages to arrive till it expires.
      * ! Pull subscriptions only. Push subscription will throw IllegalStateException
      * ! Primitive API for ADVANCED use only, officially not supported. Prefer fetch, iterate or reader.
      *