[service-bus] Documentation Review for version 7 (Azure#12569)

sdk/servicebus/service-bus/README.md

@@ -16,23 +16,23 @@ Resources for the v7.0.0 of `@azure/service-bus`:
 [Product documentation](https://azure.microsoft.com/services/service-bus/) |
 [Samples](https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/servicebus/service-bus/samples)
 
-> **NOTE**: This document has instructions, links and code snippets for the **preview** of the next version of the `@azure/service-bus` package
-> which has different APIs than the stable version. To use the stable version of the library use the below resources.
+Samples for v1 and documentation are still available here:
 
 [Source code or Readme for v1.1.10](https://github.com/Azure/azure-sdk-for-js/tree/%40azure/service-bus_1.1.10/sdk/servicebus/service-bus) |
 [Package for v1.1.10 (npm)](https://www.npmjs.com/package/@azure/service-bus/v/1.1.10) |
 [API Reference Documentation for v1.1.10](https://docs.microsoft.com/javascript/api/%40azure/service-bus/?view=azure-node-latest) |
 [Samples for @azure/service-bus v1.1.x](https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/servicebus/service-bus/samples-v1)
 
-We also provide a migration guide for users familiar with the stable package that would like to try the preview: [migration guide to move from Service Bus V1 to Service Bus V7 Preview][migrationguide]
+**NOTE**: If you are using version 1.1.10 or lower and want to migrate to the latest version
+of this package please look at our [migration guide to move from Service Bus V1 to Service Bus V7 Preview][migrationguide]
 
 ## Getting Started
 
 ### Install the package
 
-Install the preview version for the Azure Service Bus client library using npm
+Install the latest version for the Azure Service Bus client library using npm.
 
-`npm install @azure/service-bus@next`
+`npm install @azure/service-bus`
 
 ### Prerequisites
 
@@ -401,19 +401,19 @@ If you'd like to contribute to this library, please read the [contributing guide
 [apiref]: https://aka.ms/azsdk/js/service-bus/docs
 [azure_identity]: https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/identity/identity/README.md
 [defaultazurecredential]: https://github.com/Azure/azure-sdk-for-js/tree/master/sdk/identity/identity#defaultazurecredential
-[sbclient]: https://docs.microsoft.com/javascript/api/%40azure/service-bus/servicebusclient?view=azure-node-preview
-[sbclient_constructor]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebusclient?view=azure-node-preview#ServiceBusClient_string__ServiceBusClientOptions_
-[sbclient_tokencred_overload]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebusclient?view=azure-node-preview#ServiceBusClient_string__TokenCredential__ServiceBusClientOptions_
-[sbclient_createsender]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebusclient?view=azure-node-preview#createSender_string_
-[sbclient_createreceiver]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebusclient?view=azure-node-preview#createReceiver_string__CreateReceiverOptions__peekLock___
-[sbclient_acceptsession]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebusclient?view=azure-node-preview#acceptSession_string__string__AcceptSessionOptions__peekLock___
-[sender]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebussender?view=azure-node-preview
-[sender_sendmessages]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebussender?view=azure-node-preview#sendMessages_ServiceBusMessage___ServiceBusMessage_____ServiceBusMessageBatch__OperationOptionsBase_
-[receiver]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebusreceiver?view=azure-node-preview
-[receiver_receivemessages]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebusreceiver?view=azure-node-preview#receiveMessages_number__ReceiveMessagesOptions_
-[receiver_subscribe]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebusreceiver?view=azure-node-preview#subscribe_MessageHandlers_ReceivedMessageT___SubscribeOptions_
-[receiver_getmessageiterator]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebusreceiver?view=azure-node-preview#getMessageIterator_GetMessageIteratorOptions_
-[sessionreceiver]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebussessionreceiver?view=azure-node-preview
+[sbclient]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebusclient
+[sbclient_constructor]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebusclient#ServiceBusClient_string__ServiceBusClientOptions_
+[sbclient_tokencred_overload]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebusclient#ServiceBusClient_string__TokenCredential__ServiceBusClientOptions_
+[sbclient_createsender]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebusclient#createSender_string_
+[sbclient_createreceiver]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebusclient#createReceiver_string__CreateReceiverOptions__peekLock___
+[sbclient_acceptsession]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebusclient#acceptSession_string__string__AcceptSessionOptions__peekLock___
+[sender]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebussender
+[sender_sendmessages]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebussender#sendMessages_ServiceBusMessage___ServiceBusMessage_____ServiceBusMessageBatch__OperationOptionsBase_
+[receiver]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebusreceiver
+[receiver_receivemessages]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebusreceiver#receiveMessages_number__ReceiveMessagesOptions_
+[receiver_subscribe]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebusreceiver#subscribe_MessageHandlers_ReceivedMessageT___SubscribeOptions_
+[receiver_getmessageiterator]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebusreceiver#getMessageIterator_GetMessageIteratorOptions_
+[sessionreceiver]: https://docs.microsoft.com/javascript/api/@azure/service-bus/servicebussessionreceiver
 [migrationguide]: https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/servicebus/service-bus/migrationguide.md
 [docsms_messagesessions]: https://docs.microsoft.com/azure/service-bus-messaging/message-sessions
 [docsms_messagesessions_fifo]: https://docs.microsoft.com/azure/service-bus-messaging/message-sessions#first-in-first-out-fifo-pattern

sdk/servicebus/service-bus/src/dataTransformer.ts

@@ -9,7 +9,7 @@ import { logErrorStackTrace, logger } from "./log";
 /**
  * The default data transformer that will be used by the Azure SDK.
  * @internal
- * @ingore
+ * @ignore
  */
 export const defaultDataTransformer = {
   /**

sdk/servicebus/service-bus/src/receivers/receiver.ts

@@ -74,7 +74,7 @@ export interface ServiceBusReceiver {
    *
    * @throws Error if the underlying connection, client or receiver is closed.
    * @throws Error if current receiver is already in state of receiving messages.
-   * @throws MessagingError if the service returns an error while receiving messages.
+   * @throws `ServiceBusError` if the service returns an error while receiving messages.
    */
   getMessageIterator(
     options?: GetMessageIteratorOptions
@@ -87,10 +87,10 @@ export interface ServiceBusReceiver {
    * @param options A set of options to control the receive operation.
    * - `maxWaitTimeInMs`: The maximum time to wait for the first message before returning an empty array if no messages are available.
    * - `abortSignal`: The signal to use to abort the ongoing operation.
-   * @returns Promise<ReceivedMessageT[]> A promise that resolves with an array of messages.
+   * @returns Promise<ServiceBusReceivedMessage[]> A promise that resolves with an array of messages.
    * @throws Error if the underlying connection, client or receiver is closed.
    * @throws Error if current receiver is already in state of receiving messages.
-   * @throws MessagingError if the service returns an error while receiving messages.
+   * @throws `ServiceBusError` if the service returns an error while receiving messages.
    */
   receiveMessages(
     maxMessageCount: number,
@@ -105,7 +105,7 @@ export interface ServiceBusReceiver {
    * - Returns a list of messages identified by the given sequenceNumbers.
    * - Returns an empty list if no messages are found.
    * @throws Error if the underlying connection or receiver is closed.
-   * @throws MessagingError if the service returns an error while receiving deferred messages.
+   * @throws `ServiceBusError` if the service returns an error while receiving deferred messages.
    */
   receiveDeferredMessages(
     sequenceNumbers: Long | Long[],
@@ -136,7 +136,7 @@ export interface ServiceBusReceiver {
    */
   receiveMode: "peekLock" | "receiveAndDelete";
   /**
-   * @property Returns `true` if either the receiver or the client that created it has been closed
+   * @property Returns `true` if either the receiver or the client that created it has been closed.
    * @readonly
    */
   isClosed: boolean;
@@ -172,11 +172,11 @@ export interface ServiceBusReceiver {
    * The lock held on the message by the receiver is let go, making the message available again in
    * Service Bus for another receive operation.
    *
-   * @throws Error with name `SessionLockLostError` (for messages from a Queue/Subscription with sessions enabled)
+   * @throws `ServiceBusError` with the code `SessionLockLost` (for messages from a Queue/Subscription with sessions enabled)
    * if the AMQP link with which the message was received is no longer alive. This can
    * happen either because the lock on the session expired or the receiver was explicitly closed by
    * the user or the AMQP link is closed by the library due to network loss or service error.
-   * @throws Error with name `MessageLockLostError` (for messages from a Queue/Subscription with sessions not enabled)
+   * @throws `ServiceBusError` with the code `MessageLockLost` (for messages from a Queue/Subscription with sessions not enabled)
    * if the lock on the message has expired or the AMQP link with which the message was received is
    * no longer alive. The latter can happen if the receiver was explicitly closed by the user or the
    * AMQP link got closed by the library due to network loss or service error.
@@ -185,7 +185,7 @@ export interface ServiceBusReceiver {
    * @throws Error if used in `receiveAndDelete` mode because all messages received in this mode
    * are pre-settled. To avoid this error, update your code to not settle a message which is received
    * in this mode.
-   * @throws Error with name `ServiceUnavailableError` if Service Bus does not acknowledge the request to settle
+   * @throws `ServiceBusError` with the code `ServiceTimeout` if Service Bus does not acknowledge the request to settle
    * the message in time. The message may or may not have been settled successfully.
    *
    * @param propertiesToModify The properties of the message to modify while abandoning the message.
@@ -200,11 +200,11 @@ export interface ServiceBusReceiver {
    * Defers the processing of the message. Save the `sequenceNumber` of the message, in order to
    * receive it message again in the future using the `receiveDeferredMessage` method.
    *
-   * @throws Error with name `SessionLockLostError` (for messages from a Queue/Subscription with sessions enabled)
+   * @throws `ServiceBusError` with the code `SessionLockLost` (for messages from a Queue/Subscription with sessions enabled)
    * if the AMQP link with which the message was received is no longer alive. This can
    * happen either because the lock on the session expired or the receiver was explicitly closed by
    * the user or the AMQP link is closed by the library due to network loss or service error.
-   * @throws Error with name `MessageLockLostError` (for messages from a Queue/Subscription with sessions not enabled)
+   * @throws `ServiceBusError` with the code `MessageLockLost` (for messages from a Queue/Subscription with sessions not enabled)
    * if the lock on the message has expired or the AMQP link with which the message was received is
    * no longer alive. The latter can happen if the receiver was explicitly closed by the user or the
    * AMQP link got closed by the library due to network loss or service error.
@@ -213,7 +213,7 @@ export interface ServiceBusReceiver {
    * @throws Error if used in `receiveAndDelete` mode because all messages received in this mode
    * are pre-settled. To avoid this error, update your code to not settle a message which is received
    * in this mode.
-   * @throws Error with name `ServiceUnavailableError` if Service Bus does not acknowledge the request to settle
+   * @throws `ServiceBusError` with the code `ServiceTimeout` if Service Bus does not acknowledge the request to settle
    * the message in time. The message may or may not have been settled successfully.
    *
    * @param propertiesToModify The properties of the message to modify while deferring the message
@@ -228,11 +228,11 @@ export interface ServiceBusReceiver {
    * Moves the message to the deadletter sub-queue. To receive a deadletted message, create a new
    * QueueClient/SubscriptionClient using the path for the deadletter sub-queue.
    *
-   * @throws Error with name `SessionLockLostError` (for messages from a Queue/Subscription with sessions enabled)
+   * @throws `ServiceBusError` with the code `SessionLockLost` (for messages from a Queue/Subscription with sessions enabled)
    * if the AMQP link with which the message was received is no longer alive. This can
    * happen either because the lock on the session expired or the receiver was explicitly closed by
    * the user or the AMQP link is closed by the library due to network loss or service error.
-   * @throws Error with name `MessageLockLostError` (for messages from a Queue/Subscription with sessions not enabled)
+   * @throws `ServiceBusError` with the code `MessageLockLost` (for messages from a Queue/Subscription with sessions not enabled)
    * if the lock on the message has expired or the AMQP link with which the message was received is
    * no longer alive. The latter can happen if the receiver was explicitly closed by the user or the
    * AMQP link got closed by the library due to network loss or service error.
@@ -241,7 +241,7 @@ export interface ServiceBusReceiver {
    * @throws Error if used in `receiveAndDelete` mode because all messages received in this mode
    * are pre-settled. To avoid this error, update your code to not settle a message which is received
    * in this mode.
-   * @throws Error with name `ServiceUnavailableError` if Service Bus does not acknowledge the request to settle
+   * @throws `ServiceBusError` with the code `ServiceTimeout` if Service Bus does not acknowledge the request to settle
    * the message in time. The message may or may not have been settled successfully.
    *
    * @param options The DeadLetter options that can be provided while
@@ -263,7 +263,7 @@ export interface ServiceBusReceiver {
    *
    * @returns Promise<Date> - New lock token expiry date and time in UTC format.
    * @throws Error if the underlying connection, client or receiver is closed.
-   * @throws MessagingError if the service returns an error while renewing message lock.
+   * @throws ServiceBusError if the service returns an error while renewing message lock.
    */
   renewMessageLock(message: ServiceBusReceivedMessage): Promise<Date>;
 }
@@ -358,7 +358,7 @@ export class ServiceBusReceiverImpl implements ServiceBusReceiver {
    * @returns void
    * @throws Error if the underlying connection or receiver is closed.
    * @throws Error if current receiver is already in state of receiving messages.
-   * @throws MessagingError if the service returns an error while receiving messages. These are bubbled up to be handled by user provided `onError` handler.
+   * @throws ServiceBusError if the service returns an error while receiving messages. These are bubbled up to be handled by user provided `onError` handler.
    */
   private _registerMessageHandler(
     onInitialize: () => Promise<void>,

sdk/servicebus/service-bus/src/sender.ts

@@ -32,7 +32,7 @@ import { senderLogger as logger } from "./log";
 /**
  * A Sender can be used to send messages, schedule messages to be sent at a later time
  * and cancel such scheduled messages.
- * Use the `createSender` function on the ServiceBusClient instantiate a Sender.
+ * Use the `createSender` function on the ServiceBusClient to instantiate a Sender.
  * The Sender class is an abstraction over the underlying AMQP sender link.
  */
 export interface ServiceBusSender {
@@ -49,8 +49,9 @@ export interface ServiceBusSender {
    * method to send.
    * @param options - Options bag to pass an abort signal or tracing options.
    * @return Promise<void>
+   * @throws `MessagingError` with the code `MessageTooLargeError` if the provided messages do not fit in a single `ServiceBusMessageBatch`.
    * @throws Error if the underlying connection, client or sender is closed.
-   * @throws MessagingError if the service returns an error while sending messages to the service.
+   * @throws `ServiceBusError` if the service returns an error while sending messages to the service.
    */
   sendMessages(
     messages: ServiceBusMessage | ServiceBusMessage[] | ServiceBusMessageBatch,
@@ -65,7 +66,7 @@ export interface ServiceBusSender {
    *
    * @param {CreateMessageBatchOptions} [options]
    * @returns {Promise<ServiceBusMessageBatch>}
-   * @throws MessagingError if an error is encountered while sending a message.
+   * @throws `ServiceBusError` if an error is encountered while sending a message.
    * @throws Error if the underlying connection or sender has been closed.
    */
   createMessageBatch(options?: CreateMessageBatchOptions): Promise<ServiceBusMessageBatch>;
@@ -82,7 +83,7 @@ export interface ServiceBusSender {
   open(options?: OperationOptionsBase): Promise<void>;
 
   /**
-   * @property Returns `true` if either the sender or the client that created it has been closed
+   * @property Returns `true` if either the sender or the client that created it has been closed.
    * @readonly
    */
   isClosed: boolean;
@@ -98,7 +99,7 @@ export interface ServiceBusSender {
    * Save the `Long` type as-is in your application without converting to number. Since JavaScript
    * only supports 53 bit numbers, converting the `Long` to number will cause loss in precision.
    * @throws Error if the underlying connection, client or sender is closed.
-   * @throws MessagingError if the service returns an error while scheduling messages.
+   * @throws `ServiceBusError` if the service returns an error while scheduling messages.
    */
   scheduleMessages(
     messages: ServiceBusMessage | ServiceBusMessage[],
@@ -112,7 +113,7 @@ export interface ServiceBusSender {
    * @param options - Options bag to pass an abort signal or tracing options.
    * @returns Promise<void>
    * @throws Error if the underlying connection, client or sender is closed.
-   * @throws MessagingError if the service returns an error while canceling scheduled messages.
+   * @throws `ServiceBusError` if the service returns an error while canceling scheduled messages.
    */
   cancelScheduledMessages(
     sequenceNumbers: Long | Long[],