[Event Hubs Client] Docs Enhancements (#17085)

The focus of these changes is to correct a bug in the samples and to
introduce an SDK-level overview, covering each of the libraries.

eng/.docsettings.yml

@@ -148,6 +148,7 @@ known_content_issues:
   - ['sdk/extensions/Azure.Extensions.AspNetCore.Configuration.Secrets/README.md', 'azure-sdk-tools/issues/404']
   - ['sdk/extensions/Microsoft.Azure.WebJobs.Extensions.Clients/README.md','azure-sdk-tools/issues/404']
   - ['sdk/extensions/Microsoft.Extensions.Azure/README.md','#5499']
+  - ['sdk/eventhub/README.md','azure-sdk-tools/issues/42']
   - ['sdk/search/README.md','azure-sdk-tools/issues/42']
   - ['sdk/formrecognizer/Azure.AI.FormRecognizer/README.md','#5499']
   - ['sdk/formrecognizer/Azure.AI.FormRecognizer/README.md','#11492']

sdk/eventhub/Azure.Messaging.EventHubs.Processor/README.md

@@ -1,6 +1,6 @@
 # Azure Event Hubs Event Processor client library for .NET
 
-Azure Event Hubs is a highly scalable publish-subscribe service that can ingest millions of events per second and stream them to multiple consumers. This lets you process and analyze the massive amounts of data produced by your connected devices and applications. Once Event Hubs has collected the data, you can retrieve, transform and store it by using any real-time analytics provider or with batching/storage adapters.  If you would like to know more about Azure Event Hubs, you may wish to review: [What is Event Hubs](https://docs.microsoft.com/azure/event-hubs/event-hubs-about)?
+Azure Event Hubs is a highly scalable publish-subscribe service that can ingest millions of events per second and stream them to multiple consumers. This lets you process and analyze the massive amounts of data produced by your connected devices and applications. Once Event Hubs has collected the data, you can retrieve, transform, and store it by using any real-time analytics provider or with batching/storage adapters.  If you would like to know more about Azure Event Hubs, you may wish to review: [What is Event Hubs](https://docs.microsoft.com/azure/event-hubs/event-hubs-about).
 
 The Event Processor client library is a companion to the Azure Event Hubs client library, providing a stand-alone client for consuming events in a robust, durable, and scalable way that is suitable for the majority of production scenarios.  An opinionated implementation built using Azure Storage blobs, the Event Processor is recommended for:
 

sdk/eventhub/Azure.Messaging.EventHubs.Processor/samples/Sample01_HelloWorld.md

@@ -39,7 +39,7 @@ try
             // decision would have to be made as to whether the event should
             // be dropped or published on its own.
 
-            return;
+            break;
         }
     }
 

sdk/eventhub/Azure.Messaging.EventHubs.Processor/tests/Snippets/Sample01_HelloWorldLiveTests.cs

@@ -94,7 +94,7 @@ public async Task PublishEvents()
                         // decision would have to be made as to whether the event should
                         // be dropped or published on its own.
 
-                        return;
+                        break;
                     }
                 }
 

sdk/eventhub/Azure.Messaging.EventHubs/README.md

@@ -1,6 +1,6 @@
 # Azure Event Hubs client library for .NET
 
-Azure Event Hubs is a highly scalable publish-subscribe service that can ingest millions of events per second and stream them to multiple consumers. This lets you process and analyze the massive amounts of data produced by your connected devices and applications. Once Event Hubs has collected the data, you can retrieve, transform and store it by using any real-time analytics provider or with batching/storage adapters.  If you would like to know more about Azure Event Hubs, you may wish to review: [What is Event Hubs](https://docs.microsoft.com/azure/event-hubs/event-hubs-about)?
+Azure Event Hubs is a highly scalable publish-subscribe service that can ingest millions of events per second and stream them to multiple consumers. This lets you process and analyze the massive amounts of data produced by your connected devices and applications. Once Event Hubs has collected the data, you can retrieve, transform, and store it by using any real-time analytics provider or with batching/storage adapters.  If you would like to know more about Azure Event Hubs, you may wish to review: [What is Event Hubs](https://docs.microsoft.com/azure/event-hubs/event-hubs-about).
 
 The Azure Event Hubs client library allows for publishing and consuming of Azure Event Hubs events and may be used to:
 

sdk/eventhub/Azure.Messaging.EventHubs/samples/Sample01_HelloWorld.md

@@ -45,7 +45,7 @@ try
             // decision would have to be made as to whether the event should
             // be dropped or published on its own.
 
-            return;
+            break;
         }
     }
 

sdk/eventhub/Azure.Messaging.EventHubs/tests/Snippets/Sample01_HelloWorldLiveTests.cs

@@ -104,7 +104,7 @@ public async Task PublishEvents()
                         // decision would have to be made as to whether the event should
                         // be dropped or published on its own.
 
-                        return;
+                        break;
                     }
                 }
 

sdk/eventhub/README.md

@@ -0,0 +1,37 @@
+# Azure Event Hubs libraries for .NET
+
+Azure Event Hubs is a highly scalable publish-subscribe service that can ingest millions of events per second and stream them to multiple consumers. This lets you process and analyze the massive amounts of data produced by your connected devices and applications. Once Event Hubs has collected the data, you can retrieve, transform, and store it by using any real-time analytics provider or with batching/storage adapters.  If you would like to know more about Azure Event Hubs, you may wish to review: [What is Event Hubs](https://docs.microsoft.com/azure/event-hubs/event-hubs-about).
+
+## Libraries for data access
+
+The current generation of the Azure Event Hubs client library uses versions 5.0.1 and above.  Microsoft recommends using version 5.2 or higher for new applications.  If you are unable to existing applications to version 5.x, then Microsoft recommends using version 4.1 or higher.
+
+### Version 5.x
+
+The version 5.x client libraries are part of the Azure SDK for .NET. The source code for the Azure Event Hubs client libraries is available on [GitHub](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/eventhub).
+
+Use the following packages to publish and consume events from Event Hubs:
+
+| Nuget Package | Reference | Samples |
+|--------------------------------------|---------------------------------------------------------------|-------------------------------------------------------------------------------|
+| [Azure.Messaging.EventHubs](https://www.nuget.org/packages/Azure.Messaging.EventHubs)  |  [API Reference for Azure.Messaging.EventHubs](https://docs.microsoft.com/dotnet/api/azure.messaging.eventhubs?view=azure-dotnet)  |  [Samples for Azure.Messaging.EventHubs](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/eventhub/Azure.Messaging.EventHubs/samples)  |
+| [Azure.Messaging.EventHubs.Processor](https://www.nuget.org/packages/Azure.Messaging.EventHubs.Processor)  |  [API Reference for Azure.Messaging.EventHubs.Processor](https://docs.microsoft.com/dotnet/api/azure.messaging.eventhubs?view=azure-dotnet)  |  [Samples for Azure.Messaging.EventHubs.Processor](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/eventhub/Azure.Messaging.EventHubs.Processor/samples)  |
+
+### Version 4.x
+
+The source code for version 4.x of the Azure Event Hubs client libraries is available on [GitHub](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/eventhub).
+
+Use the following legacy packages to publish and consume events from Event Hubs:
+
+| Nuget Package | Reference | Samples |
+|--------------------------------------|---------------------------------------------------------------|-------------------------------------------------------------------------------|
+| [Microsoft.Azure.EventHubs](https://www.nuget.org/packages/Microsoft.Azure.EventHubs)  |  [API Reference for Microsoft.Azure.EventHubs](https://docs.microsoft.com/dotnet/api/overview/azure/eventhubs/v4?view=azure-dotnet)  |  [Samples for Azure.Messaging.EventHubs](https://github.com/Azure/azure-event-hubs/tree/master/samples/DotNet/)  |
+| [Microsoft.Azure.EventHubs.Processor](https://www.nuget.org/packages/Microsoft.Azure.EventHubs.Processor)  |  [API Reference for Microsoft.Azure.EventHubs.Processor](https://docs.microsoft.com/dotnet/api/microsoft.azure.eventhubs.processor?view=azure-dotnet)  |  [Samples for Azure.Messaging.EventHubs.Processor](https://github.com/Azure/azure-event-hubs/tree/master/samples/DotNet/)  |
+
+## Libraries for resource management
+
+Use the following library to work with the Azure Event Hubs resource provider:
+
+| Nuget Package | Reference |
+|--------------------------------------|---------------------------------------------------------------|
+| [Azure.ResourceManager.EventHubs](https://www.nuget.org/packages/Azure.ResourceManager.EventHubs)  | [API Reference for Azure.ResourceManager.EventHubs](https://docs.microsoft.com/dotnet/api/overview/azure/eventhubs/management?view=azure-dotnet)  |