Skip to content

Commit

Permalink
[service-bus] Improve doc strings for create() methods on ServiceBusC…
Browse files Browse the repository at this point in the history 
…lient (Azure#8778)

* Improve doc comments for the various overloads.

* Update documentation to reflect what the mode the user has chosen actually does.

* Meant to propagate the receiveMode to the deadLetterReceivers as well.

* Updated with similar text to Ramya's suggestion

* Let's try this one out.

* We've got those entity specific names!

* Updated with Ramya's addition to mention the dead letter queue and improve cross-advertising of features. :)

* Improve the docs a bit more with feedback from Ramya.

Also corrected an inaccuracy on the dead letter documentaion. You can't dead letter a dead lettered message!

* Add in the session enabled bit of documentation.

* Updated to include link to dead letter queues

* Updated with links to how peekLock mode works in the service bus documentation.
  • Loading branch information
@richardpark-msft
richardpark-msft authored May 11, 2020
1 parent 0bb0ec7 commit 373e27f
Showing 1 changed file with 121 additions and 24 deletions.
145 changes: 121 additions & 24 deletions sdk/servicebus/service-bus/src/serviceBusClient.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79,37 +79,67 @@ export class ServiceBusClient {
}

/**
* Creates a receiver for an Azure Service Bus queue.
* Creates a receiver for an Azure Service Bus queue in peekLock mode.
*
* In peekLock mode, the receiver has a lock on the message for the duration specified on the
* queue.
*
* Messages that are not settled within the lock duration will be redelivered as many times as
* the max delivery count set on the queue, after which they get sent to a separate dead letter
* queue.
*
* You can settle a message by calling complete(), abandon(), defer() or deadletter() methods on
* the message.
*
* More information about how peekLock and message settlement works here:
* https://docs.microsoft.com/en-us/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock
*
* @param queueName The name of the queue to receive from.
* @param receiveMode The receive mode to use (defaults to PeekLock)
* @param receiveMode The receive mode, defaulted to peekLock.
*/
createReceiver(queueName: string, receiveMode: "peekLock"): Receiver<ReceivedMessageWithLock>;
/**
* Creates a receiver for an Azure Service Bus queue.
* Creates a receiver for an Azure Service Bus queue in receiveAndDelete mode.
*
* In receiveAndDelete mode, messages are deleted from Service Bus as they are received.
*
* @param queueName The name of the queue to receive from.
* @param receiveMode The receive mode to use (defaults to PeekLock)
* @param receiveMode The receive mode, defaulted to receiveAndDelete.
*/
createReceiver(queueName: string, receiveMode: "receiveAndDelete"): Receiver<ReceivedMessage>;
/**
* Creates a receiver for an Azure Service Bus subscription.
* Creates a receiver for an Azure Service Bus subscription in peekLock mode.
*
* In peekLock mode, the receiver has a lock on the message for the duration specified on the
* subscription.
*
* Messages that are not settled within the lock duration will be redelivered as many times as
* the max delivery count set on the subscription, after which they get sent to a separate dead letter
* queue.
*
* You can settle a message by calling complete(), abandon(), defer() or deadletter() methods on
* the message.
*
* More information about how peekLock and message settlement works here:
* https://docs.microsoft.com/en-us/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock
*
* @param topicName Name of the topic for the subscription we want to receive from.
* @param subscriptionName Name of the subscription (under the `topic`) that we want to receive from.
* @param receiveMode The receive mode to use (defaults to PeekLock)
* @param receiveMode The receive mode, defaulted to peekLock.
*/
createReceiver(
topicName: string,
subscriptionName: string,
receiveMode: "peekLock"
): Receiver<ReceivedMessageWithLock>;
/**
* Creates a receiver for an Azure Service Bus subscription.
* Creates a receiver for an Azure Service Bus subscription in receiveAndDelete mode.
*
* In receiveAndDelete mode, messages are deleted from Service Bus as they are received.
*
* @param topicName Name of the topic for the subscription we want to receive from.
* @param subscriptionName Name of the subscription (under the `topic`) that we want to receive from.
* @param receiveMode The receive mode to use (defaults to PeekLock)
* @param receiveMode The receive mode, defaulted to receiveAndDelete.
*/
createReceiver(
topicName: string,
Expand Down Expand Up @@ -152,10 +182,23 @@ export class ServiceBusClient {
}

/**
* Creates a receiver for an Azure Service Bus queue.
* Creates a receiver for a session enabled Azure Service Bus queue in peekLock mode.
*
* In peekLock mode, the receiver has a lock on the session for the duration specified on the
* queue.
*
* Messages that are not settled within the lock duration will be redelivered as many times as
* the max delivery count set on the queue, after which they get sent to a separate dead letter
* queue.
*
* You can settle a message by calling complete(), abandon(), defer() or deadletter() methods on
* the message.
*
* More information about how peekLock and message settlement works here:
* https://docs.microsoft.com/en-us/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock
*
* @param queueName The name of the queue to receive from.
* @param receiveMode The receive mode to use (defaults to PeekLock)
* @param receiveMode The receive mode, defaulted to peekLock.
* @param options Options for the receiver itself.
*/
createSessionReceiver(
Expand All @@ -164,10 +207,12 @@ export class ServiceBusClient {
options?: CreateSessionReceiverOptions
): Promise<SessionReceiver<ReceivedMessageWithLock>>;
/**
* Creates a receiver for an Azure Service Bus queue.
* Creates a receiver for a session enabled Azure Service Bus queue in receiveAndDelete mode.
*
* In receiveAndDelete mode, messages are deleted from Service Bus as they are received.
*
* @param queueName The name of the queue to receive from.
* @param receiveMode The receive mode to use (defaults to PeekLock)
* @param receiveMode The receive mode, defaulted to receiveAndDelete.
* @param options Options for the receiver itself.
*/
createSessionReceiver(
Expand All @@ -176,11 +221,24 @@ export class ServiceBusClient {
options?: CreateSessionReceiverOptions
): Promise<SessionReceiver<ReceivedMessage>>;
/**
* Creates a receiver for an Azure Service Bus subscription.
* Creates a receiver for a session enabled Azure Service Bus subscription in peekLock mode.
*
* In peekLock mode, the receiver has a lock on the session for the duration specified on the
* subscription.
*
* Messages that are not settled within the lock duration will be redelivered as many times as
* the max delivery count set on the subscription, after which they get sent to a separate dead letter
* queue.
*
* You can settle a message by calling complete(), abandon(), defer() or deadletter() methods on
* the message.
*
* More information about how peekLock and message settlement works here:
* https://docs.microsoft.com/en-us/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock
*
* @param topicName Name of the topic for the subscription we want to receive from.
* @param subscriptionName Name of the subscription (under the `topic`) that we want to receive from.
* @param receiveMode The receive mode to use (defaults to PeekLock)
* @param receiveMode The receive mode, defaulted to peekLock.
* @param options Options for the receiver itself.
*/
createSessionReceiver(
Expand All @@ -190,11 +248,13 @@ export class ServiceBusClient {
options?: CreateSessionReceiverOptions
): Promise<SessionReceiver<ReceivedMessageWithLock>>;
/**
* Creates a receiver for an Azure Service Bus subscription.
* Creates a receiver for a session enabled Azure Service Bus subscription in receiveAndDelete mode.
*
* In receiveAndDelete mode, messages are deleted from Service Bus as they are received.
*
* @param topicName Name of the topic for the subscription we want to receive from.
* @param subscriptionName Name of the subscription (under the `topic`) that we want to receive from.
* @param receiveMode The receive mode to use (defaults to PeekLock)
* @param receiveMode The receive mode, defaulted to receiveAndDelete.
* @param options Options for the receiver itself.
*/
createSessionReceiver(
Expand Down Expand Up @@ -271,43 +331,80 @@ export class ServiceBusClient {
// }

/**
* Creates a receiver for an Azure Service Bus queue's dead letter queue.
* Creates a receiver for an Azure Service Bus queue's dead letter queue in peekLock mode.
*
* In peekLock mode, the receiver has a lock on the message for the duration specified on the
* queue.
*
* In peekLock mode, the receiver has a lock on the message for the duration specified on the
* queue. Messages that are not settled within the lock duration will be redelivered.
*
* You can settle a message by calling complete(), abandon() or defer() methods on
* the message.
*
* See here for more information about dead letter queues:
* https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-dead-letter-queues
*
* More information about how peekLock and message settlement works here:
* https://docs.microsoft.com/en-us/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock
*
* @param queueName The name of the queue to receive from.
* @param receiveMode The receive mode to use (defaults to PeekLock)
* @param receiveMode The receive mode, defaulted to peekLock.
*/
createDeadLetterReceiver(
queueName: string,
receiveMode: "peekLock"
): Receiver<ReceivedMessageWithLock>;
/**
* Creates a receiver for an Azure Service Bus queue's dead letter queue.
* Creates a receiver for an Azure Service Bus queue's dead letter queue in receiveAndDelete mode.
*
* In receiveAndDelete mode, messages are deleted from Service Bus as they are received.
*
* See here for more information about dead letter queues:
* https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-dead-letter-queues
*
* @param queueName The name of the queue to receive from.
* @param receiveMode The receive mode to use (defaults to PeekLock)
* @param receiveMode The receive mode, defaulted to receiveAndDelete.
*/
createDeadLetterReceiver(
queueName: string,
receiveMode: "receiveAndDelete"
): Receiver<ReceivedMessage>;
/**
* Creates a receiver for an Azure Service Bus subscription's dead letter queue.
* Creates a receiver for an Azure Service Bus subscription's dead letter queue in peekLock mode.
*
* In peekLock mode, the receiver has a lock on the message for the duration specified on the
* subscription. Messages that are not settled within the lock duration will be redelivered.
*
* You can settle a message by calling complete(), abandon() or defer() methods on
* the message.
*
* See here for more information about dead letter queues:
* https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-dead-letter-queues
*
* More information about how peekLock and message settlement works here:
* https://docs.microsoft.com/en-us/azure/service-bus-messaging/message-transfers-locks-settlement#peeklock
*
* @param topicName Name of the topic for the subscription we want to receive from.
* @param subscriptionName Name of the subscription (under the `topic`) that we want to receive from.
* @param receiveMode The receive mode to use (defaults to PeekLock)
* @param receiveMode The receive mode, defaulted to peekLock.
*/
createDeadLetterReceiver(
topicName: string,
subscriptionName: string,
receiveMode: "peekLock"
): Receiver<ReceivedMessageWithLock>;
/**
* Creates a receiver for an Azure Service Bus subscription's dead letter queue.
* Creates a receiver for an Azure Service Bus subscription's dead letter queue in receiveAndDelete mode.
*
* In receiveAndDelete mode, messages are deleted from Service Bus as they are received.
*
* See here for more information about dead letter queues:
* https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-dead-letter-queues
*
* @param topicName Name of the topic for the subscription we want to receive from.
* @param subscriptionName Name of the subscription (under the `topic`) that we want to receive from.
* @param receiveMode The receive mode to use (defaults to PeekLock)
* @param receiveMode The receive mode, defaulted to receiveAndDelete.
*/
createDeadLetterReceiver(
topicName: string,
Expand Down

0 comments on commit 373e27f

Please sign in to comment.