[TA] Improve documentation for custom features (Azure#24947)

christothes · Oct 27, 2021 · 9183834 · 9183834
1 parent afbc564
commit 9183834
Show file tree

Hide file tree

Showing 19 changed files with 124 additions and 42 deletions.
diff --git a/sdk/textanalytics/Azure.AI.TextAnalytics/README.md b/sdk/textanalytics/Azure.AI.TextAnalytics/README.md
@@ -3,12 +3,11 @@ Azure Cognitive Services Text Analytics is a cloud service that provides advance
 * Language Detection
 * Sentiment Analysis
 * Key Phrase Extraction
-* Named Entity Recognition
-* Personally Identifiable Information (PII) Recognition
-* Linked Entity Recognition
+* Entity Recognition (Named, Linked, and Personally Identifiable Information (PII) entities)
 * Healthcare Recognition
-* Running multiple actions in one or more documents
 * Extractive Text Summarization
+* Custom Entity Recognition
+* Custom Single and Multi Category Classification
 
 [Source code][textanalytics_client_src] | [Package (NuGet)][textanalytics_nuget_package] | [API reference documentation][textanalytics_refdocs] | [Product documentation][textanalytics_docs] | [Samples][textanalytics_samples]
 
@@ -25,7 +24,7 @@ This table shows the relationship between SDK versions and supported API version
 
 |SDK version|Supported API version of service
 |-|- |
-|5.2.0-beta.1 | 3.0, 3.1, 3.2-preview.1 (default)
+|5.2.0-beta.2 | 3.0, 3.1, 3.2-preview.2 (default)
 |5.1.0  | 3.0, 3.1 (default)
 |5.0.0  | 3.0
 |1.0.X | 3.0
@@ -771,6 +770,9 @@ Samples are provided for each main functional area, and for each area, samples a
 - [Recognize Linked Entities][recognize_linked_entities_sample]
 - [Recognize Healthcare Entities][analyze_healthcare_sample]
 - [Perform Extractive Text Summarization][extract_summary_sample]
+- [Custom Entity Recognition][recognize_custom_entities_sample]
+- [Custom Single Category Classification][single_category_classify_sample]
+- [Custom Multi Category Classification][multi_category_classify_sample]
 
 ### Advanced samples
 - [Analyze Sentiment with Opinion Mining][analyze_sentiment_opinion_mining_sample]
@@ -831,6 +833,9 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con
 [recognize_pii_entities_sample]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/textanalytics/Azure.AI.TextAnalytics/samples/Sample5_RecognizePiiEntities.md
 [recognize_linked_entities_sample]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/textanalytics/Azure.AI.TextAnalytics/samples/Sample6_RecognizeLinkedEntities.md
 [mock_client_sample]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/textanalytics/Azure.AI.TextAnalytics/samples/Sample_MockClient.md
+[recognize_custom_entities_sample]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/textanalytics/Azure.AI.TextAnalytics/samples/Sample9_RecognizeCustomEntities.md
+[single_category_classify_sample]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/textanalytics/Azure.AI.TextAnalytics/samples/Sample10_SingleCategoryClassify.md
+[multi_category_classify_sample]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/textanalytics/Azure.AI.TextAnalytics/samples/Sample11_MultiCategoryClassify.md
 
 [azure_cli]: https://docs.microsoft.com/cli/azure
 [azure_sub]: https://azure.microsoft.com/free/dotnet/

diff --git a/sdk/textanalytics/Azure.AI.TextAnalytics/samples/README.md b/sdk/textanalytics/Azure.AI.TextAnalytics/samples/README.md
@@ -15,12 +15,11 @@ Azure Cognitive Services Text Analytics is a cloud service that provides advance
 * Language Detection
 * Sentiment Analysis
 * Key Phrase Extraction
-* Named Entity Recognition
-* Personally Identifiable Information (PII) Recognition
-* Linked Entity Recognition
+* Entity Recognition (Named, Linked, and Personally Identifiable Information (PII) entities)
 * Healthcare Recognition
-* Running multiple actions in one or more documents
 * Extractive Text Summarization
+* Custom Entity Recognition
+* Custom Single and Multi Category Classification
 
 ## Common scenarios samples
 - [Detect Language](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/textanalytics/Azure.AI.TextAnalytics/samples/Sample1_DetectLanguage.md)
@@ -31,6 +30,9 @@ Azure Cognitive Services Text Analytics is a cloud service that provides advance
 - [Recognize Linked Entities](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/textanalytics/Azure.AI.TextAnalytics/samples/Sample6_RecognizeLinkedEntities.md)
 - [Analyze Healthcare Entities](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/textanalytics/Azure.AI.TextAnalytics/samples/Sample7_AnalyzeHealthcareEntities.md)
 - [Perform Extractive Text Summarization](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/textanalytics/Azure.AI.TextAnalytics/samples/Sample8_ExtractSummary.md)
+- [Custom Entity Recognition](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/textanalytics/Azure.AI.TextAnalytics/samples/Sample9_RecognizeCustomEntities.md)
+- [Custom Single Category Classification](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/textanalytics/Azure.AI.TextAnalytics/samples/Sample10_SingleCategoryClassify.md)
+- [Custom Multi Category Classification](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/textanalytics/Azure.AI.TextAnalytics/samples/Sample11_MultiCategoryClassify.md)
 
 ## Advanced samples
 - [Analyze Sentiment with Opinion Mining](https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/textanalytics/Azure.AI.TextAnalytics/samples/Sample2.1_AnalyzeSentimentWithOpinionMining.md)

diff --git a/...textanalytics/Azure.AI.TextAnalytics/samples/Sample10_SingleCategoryClassify.md b/...textanalytics/Azure.AI.TextAnalytics/samples/Sample10_SingleCategoryClassify.md
@@ -1,5 +1,7 @@
 # Perform Custom Single Category Classification on Documents
-This sample demonstrates how to run a single category classification action in one or more documents. To get started you will need a Text Analytics endpoint and credentials. See [README][README] for links and instructions.
+This sample demonstrates how to run a single category classification action in one or more documents. In order to use this feature, you need to train a model with your own data. For more information on how to do the training, see [train model][train_model].
+
+To get started you will need a Text Analytics endpoint and credentials. See [README][README] for links and instructions.
 
 ## Creating a `TextAnalyticsClient`
 
@@ -29,6 +31,7 @@ var batchInput = new List<string>
 };
 
 // Set project and deployment names of the target model
+// To train a model to classify your documents, see https://aka.ms/azsdk/textanalytics/customfunctionalities
 string projectName = "<projectName>";
 string deploymentName = "<deploymentName>";
 
@@ -82,10 +85,11 @@ await foreach (AnalyzeActionsResult documentsInPage in operation.Value)
 
 To see the full example source files, see:
 
-* [Synchronously SingleCategoryClassify](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/textanalytics/Azure.AI.TextAnalytics/tests/samples/Sample10_SingleCategoryClassify.cs)
-* [Asynchronously SingleCategoryClassify](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/textanalytics/Azure.AI.TextAnalytics/tests/samples/Sample10_SingleCategoryClassifyAsync.cs)
-* [Synchronously SingleCategoryClassify Convenience](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/textanalytics/Azure.AI.TextAnalytics/tests/samples/Sample10_SingleCategoryClassifyConvenience.cs)
-* [Asynchronously SingleCategoryClassify Convenience](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/textanalytics/Azure.AI.TextAnalytics/tests/samples/Sample10_SingleCategoryClassifyConvenienceAsync.cs)
+* [Synchronously Single Category Classify](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/textanalytics/Azure.AI.TextAnalytics/tests/samples/Sample10_SingleCategoryClassify.cs)
+* [Asynchronously Single Category Classify](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/textanalytics/Azure.AI.TextAnalytics/tests/samples/Sample10_SingleCategoryClassifyAsync.cs)
+* [Synchronously Single Category Classify Convenience](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/textanalytics/Azure.AI.TextAnalytics/tests/samples/Sample10_SingleCategoryClassifyConvenience.cs)
+* [Asynchronously Single Category Classify Convenience](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/textanalytics/Azure.AI.TextAnalytics/tests/samples/Sample10_SingleCategoryClassifyConvenienceAsync.cs)
 
+[train_model]: https://aka.ms/azsdk/textanalytics/customfunctionalities
 [DefaultAzureCredential]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/README.md
 [README]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/textanalytics/Azure.AI.TextAnalytics/README.md
diff --git a/...ples/Sample11_ClassifyCustomCategories.md → ...samples/Sample11_MultiCategoryClassify.md b/...ples/Sample11_ClassifyCustomCategories.md → ...samples/Sample11_MultiCategoryClassify.md
@@ -1,5 +1,7 @@
 # Perform Custom Multiple Category Classification in Documents
-This sample demonstrates how to run a Multi Category Classification action in one or more documents. To get started you will need a Text Analytics endpoint and credentials. See [README][README] for links and instructions.
+This sample demonstrates how to run a Multi Category Classification action in one or more documents.  In order to use this feature, you need to train a model with your own data. For more information on how to do the training, see [train model][train_model].
+
+To get started you will need a Text Analytics endpoint and credentials. See [README][README] for links and instructions.
 
 ## Creating a `TextAnalyticsClient`
 
@@ -29,6 +31,7 @@ var batchInput = new List<string>
 };
 
 // Set project and deployment names of the target model
+// To train a model to classify your documents, see https://aka.ms/azsdk/textanalytics/customfunctionalities            
 string projectName = "<projectName>";
 string deploymentName = "<deploymentName>";
 
@@ -96,5 +99,6 @@ To see the full example source files, see:
 * [Synchronously Multi Category Classify Convenience](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/textanalytics/Azure.AI.TextAnalytics/tests/samples/Sample11_MultiCategoryClassifyConvenience.cs)
 * [Asynchronously Multi Category Classify Convenience](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/textanalytics/Azure.AI.TextAnalytics/tests/samples/Sample11_MultiCategoryClassifyConvenienceAsync.cs)
 
+[train_model]: https://aka.ms/azsdk/textanalytics/customfunctionalities
 [DefaultAzureCredential]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/README.md
 [README]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/textanalytics/Azure.AI.TextAnalytics/README.md
diff --git a/...textanalytics/Azure.AI.TextAnalytics/samples/Sample9_RecognizeCustomEntities.md b/...textanalytics/Azure.AI.TextAnalytics/samples/Sample9_RecognizeCustomEntities.md
@@ -1,5 +1,7 @@
 # Recognizing Custom Entities from Documents
-This sample demonstrates how to recognize custom entities in one or more documents. To get started you'll need a Text Analytics endpoint and credentials.  See [README][README] for links and instructions.
+This sample demonstrates how to recognize custom entities in one or more documents. In order to use this feature, you need to train a model with your own data. For more information on how to do the training, see [train model][train_model].
+
+To get started you'll need a Text Analytics endpoint and credentials.  See [README][README] for links and instructions.
 
 ## Creating a `TextAnalyticsClient`
 
@@ -41,6 +43,7 @@ var batchDocuments = new List<TextDocumentInput>
 };
 
 // prepare actions.
+// To train a model to recognize your custom entities, see https://aka.ms/azsdk/textanalytics/customentityrecognition
 string projectName = "<projectName>";
 string deploymentName = "<deploymentName>";
 var actions = new TextAnalyticsActions()
@@ -108,6 +111,7 @@ To see the full example source files, see:
 * [Asynchronously RecognizeCustomEntities Convenience](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/textanalytics/Azure.AI.TextAnalytics/tests/samples/Sample9_RecognizeCustomEntitiesConvenienceAsync.cs)
 
 <!-- LINKS -->
+[train_model]: https://aka.ms/azsdk/textanalytics/customentityrecognition
 [azure_language_studio]: https://language.azure.com/
 [README]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/textanalytics/Azure.AI.TextAnalytics/README.md
 [DefaultAzureCredential]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/README.md
diff --git a/sdk/textanalytics/Azure.AI.TextAnalytics/src/TextAnalyticsActions.cs b/sdk/textanalytics/Azure.AI.TextAnalytics/src/TextAnalyticsActions.cs
@@ -57,6 +57,8 @@ public TextAnalyticsActions()
 
         /// <summary>
         /// The set of <see cref="RecognizeCustomEntitiesAction"/> that will get executed on the input documents.
+        /// To train a model to recognize your custom entities, see the
+        /// <see href="https://aka.ms/azsdk/textanalytics/customentityrecognition">documentation</see>.
         /// </summary>
         /// <remarks>
         /// This property only applies for <see cref="TextAnalyticsClientOptions.ServiceVersion.V3_2_Preview_2"/> and up.
@@ -65,6 +67,8 @@ public TextAnalyticsActions()
 
         /// <summary>
         /// The set of <see cref="SingleCategoryClassifyAction"/> that will get executed on the input documents.
+        /// To train a model to classify your documents, see the
+        /// <see href="https://aka.ms/azsdk/textanalytics/customfunctionalities">documentation</see>.
         /// </summary>
         /// <remarks>
         /// This property only applies for <see cref="TextAnalyticsClientOptions.ServiceVersion.V3_2_Preview_2"/> and up.
@@ -73,6 +77,8 @@ public TextAnalyticsActions()
 
         /// <summary>
         /// The set of <see cref="MultiCategoryClassifyAction"/> that will get executed on the input documents.
+        /// To train a model to classify your documents, see the
+        /// <see href="https://aka.ms/azsdk/textanalytics/customfunctionalities">documentation</see>.
         /// </summary>
         /// <remarks>
         /// This property only applies for <see cref="TextAnalyticsClientOptions.ServiceVersion.V3_2_Preview_2"/> and up.