[event-hubs] doc improvements (#9342)

* [event-hubs] explain empty events

* [event-hubs] readme update for 8798

* [event-hubs] migration-guide checkpointing 8419

* update changelog for 5.2.1

* Update sdk/eventhub/event-hubs/migrationguide.md

Co-authored-by: Richard Park <51494936+richardpark-msft@users.noreply.github.com>

* Decided to be more ambitious for the release date

Co-authored-by: Richard Park <51494936+richardpark-msft@users.noreply.github.com>

sdk/eventhub/event-hubs/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Release History
 
-## 5.2.1 (Unreleased)
+## 5.2.1 (2020-06-08)
 
 - Fixes issue [#8584](https://github.com/Azure/azure-sdk-for-js/issues/8584)
   where attempting to create AMQP links when the AMQP connection was in the

sdk/eventhub/event-hubs/README.md

@@ -399,7 +399,7 @@ hence sending events is not possible.
 
 - Please notice that the connection string needs to be for an
   [Event Hub-compatible endpoint](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-messages-read-builtin)
-  e.g. "Endpoint=sb://my-iothub-namespace-[uid].servicebus.windows.net/;SharedAccessKeyName=my-SA-name;SharedAccessKey=my-SA-key;EntityPath=my-iot-hub-name"
+  (e.g. "Endpoint=sb://my-iothub-namespace-[uid].servicebus.windows.net/;SharedAccessKeyName=my-SA-name;SharedAccessKey=my-SA-key;EntityPath=my-iot-hub-name")
 
 ```javascript
 const { EventHubConsumerClient } = require("@azure/event-hubs");

sdk/eventhub/event-hubs/migrationguide.md

@@ -38,6 +38,10 @@ We've also merged the functionality from `EventProcessorHost` from the `@azure/e
 `EventHubConsumerClient` in the `@azure/event-hubs` package, allowing `EventHubConsumerClient` to be the single
 point of entry for receiving of any type (from single partition, all partitions, or with load balancing and checkpointing features) within Event Hubs.
 
+Important note on checkpoints: `EventHubConsumerClient` does not support legacy checkpoint data.
+In order to meet the goals set for unifying checkpoint data across languages for the new set of Event Hubs libraries and to make
+improvements to the algorithm used for managing partition ownership, breaking changes were necessary.
+
 ### Granular control over retries
 
 Retry logic and tuning has been externalized, allowing for better configuration

sdk/eventhub/event-hubs/samples/javascript/receiveEvents.js

@@ -35,6 +35,12 @@ async function main() {
     {
       // The callback where you add your code to process incoming events
       processEvents: async (events, context) => {
+        // Note: It is possible for `events` to be an empty array.
+        // This can happen if there were no new events to receive
+        // in the `maxWaitTimeInSeconds`, which is defaulted to
+        // 60 seconds.
+        // The `maxWaitTimeInSeconds` can be changed by setting
+        // it in the `options` passed to `subscribe()`.
         for (const event of events) {
           console.log(
             `Received event: '${event.body}' from partition: '${context.partitionId}' and consumer group: '${context.consumerGroup}'`

sdk/eventhub/event-hubs/samples/typescript/src/receiveEvents.ts

@@ -36,6 +36,12 @@ export async function main() {
     {
       // The callback where you add your code to process incoming events
       processEvents: async (events, context) => {
+        // Note: It is possible for `events` to be an empty array.
+        // This can happen if there were no new events to receive
+        // in the `maxWaitTimeInSeconds`, which is defaulted to
+        // 60 seconds.
+        // The `maxWaitTimeInSeconds` can be changed by setting
+        // it in the `options` passed to `subscribe()`.
         for (const event of events) {
           console.log(
             `Received event: '${event.body}' from partition: '${context.partitionId}' and consumer group: '${context.consumerGroup}'`

sdk/eventhub/event-hubs/src/eventHubConsumerClientModels.ts

@@ -117,6 +117,12 @@ export interface SubscriptionEventHandlers {
    * The `updateCheckpoint()` method on the context can be used to update checkpoints in the `CheckpointStore`
    * (if one was provided to the client). Use this in frequent intervals to mark events that have been processed
    * so that the client can restart from such checkpoints in the event of a restart or error recovery.
+   * 
+   * Note: It is possible for received events to be an empty array.
+   * This can happen if there are no new events to receive
+   * in the `maxWaitTimeInSeconds`, which is defaulted to 60 seconds.
+   * The `maxWaitTimeInSeconds` can be changed by setting
+   * it in the `options` passed to `subscribe()`.
    */
   processEvents: ProcessEventsHandler;
   /**