[FR] Update docstrings (Azure#17345)

* first rounds:

* improve docstring and cleanup some code

* PR feedback

sdk/formrecognizer/Azure.AI.FormRecognizer/README.md

@@ -116,7 +116,7 @@ var client = new FormRecognizerClient(new Uri(endpoint), new DefaultAzureCredent
 - Training custom models to recognize specific fields and values you specify by labeling your custom forms.  A `CustomFormModel` is returned indicating the fields the model will extract, as well as the estimated accuracy for each field.
 - Managing models created in your account.
 - Copying a custom model from one Form Recognizer resource to another.
-- Creating a composed model from a collection of existing trained models with labels.
+- Creating a composed model from a collection of existing models trained with labels.
 
 See examples for [Train a Model](#train-a-model) and [Manage Custom Models](#manage-custom-models).
 

sdk/formrecognizer/Azure.AI.FormRecognizer/src/AccountProperties.cs

@@ -6,7 +6,7 @@
 namespace Azure.AI.FormRecognizer.Training
 {
     /// <summary>
-    /// Contains general information about a Cognitive Services Account, such as the number
+    /// Contains general information about the Form Recognizer resource, such as the number
     /// of models and account limits.
     /// </summary>
     public class AccountProperties
@@ -21,20 +21,20 @@ internal AccountProperties(ModelsSummary summary)
         /// Initializes a new instance of the <see cref="AccountProperties"/> class.
         /// </summary>
         /// <param name="customModelCount">The current count of trained custom models.</param>
-        /// <param name="customModelLimit">The maximum number of models that can be trained for this subscription.</param>
+        /// <param name="customModelLimit">The maximum number of models that can be trained for this account.</param>
         internal AccountProperties(int customModelCount, int customModelLimit)
         {
             CustomModelCount = customModelCount;
             CustomModelLimit = customModelLimit;
         }
 
         /// <summary>
-        /// The current count of trained custom models.
+        /// The current count of trained custom models in this account.
         /// </summary>
         public int CustomModelCount { get; }
 
         /// <summary>
-        /// The maximum number of models that can be trained for this subscription.
+        /// The maximum number of models that can be trained for this account.
         /// </summary>
         public int CustomModelLimit { get; }
     }

sdk/formrecognizer/Azure.AI.FormRecognizer/src/CopyModelOperation.cs

@@ -78,7 +78,8 @@ public override CustomFormModelInfo Value
         public override bool HasValue => _value != null;
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="CopyModelOperation"/> class.
+        /// Initializes a new instance of the <see cref="CopyModelOperation"/> class which
+        /// tracks the status of the long-running operation for copying a custom model into a target Form Recognizer resource.
         /// </summary>
         /// <param name="operationId">The ID of this operation.</param>
         /// <param name="targetModelId">Model ID in the target Form Recognizer resource.</param>

sdk/formrecognizer/Azure.AI.FormRecognizer/src/CreateComposedModelOperation.cs

@@ -6,14 +6,17 @@
 namespace Azure.AI.FormRecognizer.Training
 {
     /// <summary>
-    /// Tracks the status of a long-running operation for training a model from a collection of custom forms.
+    /// Tracks the status of a long-running operation for creating a composed model from a
+    /// collection of existing models trained with labels.
     /// </summary>
     public class CreateComposedModelOperation : CreateCustomFormModelOperation
     {
         internal CreateComposedModelOperation(string location, FormRecognizerRestClient allOperations, ClientDiagnostics diagnostics) : base(location, allOperations, diagnostics) { }
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="TrainingOperation"/> class.
+        /// Initializes a new instance of the <see cref="CreateComposedModelOperation"/> class which
+        /// tracks the status of a long-running operation for creating a composed model from a
+        /// collection of existing models trained with labels.
         /// </summary>
         /// <param name="operationId">The ID of this operation.</param>
         /// <param name="client">The client used to check for completion.</param>

sdk/formrecognizer/Azure.AI.FormRecognizer/src/CreateCustomFormModelOperation.cs

@@ -12,7 +12,7 @@
 namespace Azure.AI.FormRecognizer.Training
 {
     /// <summary>
-    /// Tracks the status of a long-running operation for training a model from a collection of custom forms.
+    /// Tracks the status of a long-running operation for creating a custom model.
     /// </summary>
     public class CreateCustomFormModelOperation : Operation<CustomFormModel>
     {
@@ -73,7 +73,7 @@ public override CustomFormModel Value
         /// </summary>
         /// <remarks>
         /// The last response returned from the server during the lifecycle of this instance.
-        /// An instance of <see cref="TrainingOperation"/> sends requests to a server in UpdateStatusAsync, UpdateStatus, and other methods.
+        /// An instance of <see cref="CreateCustomFormModelOperation"/> sends requests to a server in UpdateStatusAsync, UpdateStatus, and other methods.
         /// Responses from these requests can be accessed using GetRawResponse.
         /// </remarks>
         public override Response GetRawResponse() => _response;
@@ -116,7 +116,8 @@ internal CreateCustomFormModelOperation(string location, FormRecognizerRestClien
         }
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="TrainingOperation"/> class.
+        /// Initializes a new instance of the <see cref="CreateCustomFormModelOperation"/> class which
+        /// tracks the status of a long-running operation for creating a custom model.
         /// </summary>
         /// <param name="operationId">The ID of this operation.</param>
         /// <param name="client">The client used to check for completion.</param>
@@ -159,7 +160,7 @@ private async ValueTask<Response> UpdateStatusAsync(bool async, CancellationToke
         {
             if (!_hasCompleted)
             {
-                using DiagnosticScope scope = _diagnostics.CreateScope($"{nameof(TrainingOperation)}.{nameof(UpdateStatus)}");
+                using DiagnosticScope scope = _diagnostics.CreateScope($"{nameof(CreateCustomFormModelOperation)}.{nameof(UpdateStatus)}");
                 scope.Start();
 
                 try

sdk/formrecognizer/Azure.AI.FormRecognizer/src/CustomFormModel.cs

@@ -71,7 +71,7 @@ internal CustomFormModel(
         public string ModelName { get; }
 
         /// <summary>
-        /// Model properties, like for example, if a model is composed.
+        /// Properties of a model, such as whether the model is a composed model or not.
         /// </summary>
         [CodeGenMember("Attributes")]
         public CustomFormModelProperties Properties { get; }

sdk/formrecognizer/Azure.AI.FormRecognizer/src/CustomFormModelInfo.cs

@@ -40,7 +40,7 @@ internal CustomFormModelInfo(string modelId, CustomFormModelStatus status, DateT
         public string ModelName { get; }
 
         /// <summary>
-        /// Model properties, like for example, if a model is composed.
+        /// Properties of a model, such as whether the model is a composed model or not.
         /// </summary>
         [CodeGenMember("Attributes")]
         public CustomFormModelProperties Properties { get; }

sdk/formrecognizer/Azure.AI.FormRecognizer/src/CustomFormModelProperties.cs

@@ -5,6 +5,9 @@
 
 namespace Azure.AI.FormRecognizer.Training
 {
+    /// <summary>
+    /// Properties of a model, such as whether the model is a composed model or not.
+    /// </summary>
     [CodeGenModel("Attributes")]
     public partial class CustomFormModelProperties
     {

sdk/formrecognizer/Azure.AI.FormRecognizer/src/FieldBoundingBox.cs

@@ -5,7 +5,6 @@
 using System.Collections.Generic;
 using System.Drawing;
 using System.Linq;
-using Azure.Core;
 
 namespace Azure.AI.FormRecognizer.Models
 {

sdk/formrecognizer/Azure.AI.FormRecognizer/src/FieldValueType.cs

@@ -58,7 +58,7 @@ public enum FieldValueType
         Dictionary,
 
         /// <summary>
-        /// Used for <see cref="FieldValueSelectionMark"/> type.
+        /// Used for <see cref="SelectionMarkState"/> type.
         /// </summary>
         SelectionMark
     }

sdk/formrecognizer/Azure.AI.FormRecognizer/src/FormElement.cs

@@ -5,7 +5,7 @@ namespace Azure.AI.FormRecognizer.Models
 {
     /// <summary>
     /// Represents a form element recognized from the input document. Its text can be a line,
-    /// a word, the content of a table cell, etc.
+    /// a word, the content of a table cell, a selection mark, etc.
     /// </summary>
     public abstract class FormElement
     {

sdk/formrecognizer/Azure.AI.FormRecognizer/src/FormFieldOfT.cs

@@ -12,7 +12,8 @@ public class FormField<T>
 #pragma warning restore SA1649 // File name should match first type name
     {
         /// <summary>
-        /// Initializes a new instance of the <see cref="FormField{T}"/> class.
+        /// Initializes a new instance of the <see cref="FormField{T}"/> class which
+        /// represents a field recognized in the input form, where the field's value is of a known type.
         /// </summary>
         /// <param name="field">The weakly-typed field this instance is associated with.</param>
         /// <param name="value">The strongly-typed value of this <see cref="FormField{T}"/>.</param>

sdk/formrecognizer/Azure.AI.FormRecognizer/src/FormPage.cs

@@ -6,7 +6,8 @@
 namespace Azure.AI.FormRecognizer.Models
 {
     /// <summary>
-    /// Represents a page recognized from the input document. Contains lines, words, tables and page metadata.
+    /// Represents a page recognized from the input document. Contains lines, words, tables,
+    /// selection marks, and page metadata.
     /// </summary>
     public class FormPage
     {
@@ -41,7 +42,7 @@ internal FormPage(PageResult pageResult, IReadOnlyList<ReadResult> readResults,
         /// <param name="width">The width of the image/PDF in pixels/inches, respectively.</param>
         /// <param name="height">The height of the image/PDF in pixels/inches, respectively.</param>
         /// <param name="textAngle">The general orientation of the text in clockwise direction, measured in degrees between (-180, 180].</param>
-        /// <param name="unit">The unit used by the width, height and <see cref="FieldBoundingBox"/> properties. For images, the unit is &quot;pixel&quot;. For PDF, the unit is &quot;inch&quot;.</param>
+        /// <param name="unit">The unit used by the width, height and <see cref="FieldBoundingBox"/> properties. For images, the unit is pixel. For PDF, the unit is inch.</param>
         /// <param name="lines">A list of recognized lines of text.</param>
         /// <param name="tables">A list of recognized tables contained in this page.</param>
         /// <param name="selectionMarks">A list of recognized selection marks contained in this page.</param>
@@ -79,7 +80,7 @@ internal FormPage(int pageNumber, float width, float height, float textAngle, Le
 
         /// <summary>
         /// The unit used by the width, height and <see cref="FieldBoundingBox"/> properties. For images, the unit is
-        /// &quot;pixel&quot;. For PDF, the unit is &quot;inch&quot;.
+        /// pixel. For PDF, the unit is inch.
         /// </summary>
         public LengthUnit Unit { get; }