[MetricsAdvisor] Improve docstrings for whole client

sdk/metricsadvisor/Azure.AI.MetricsAdvisor/src/DataFeedFilter.cs

@@ -19,12 +19,14 @@ public DataFeedFilter()
         }
 
         /// <summary>
-        /// Filters the result by <see cref="DataFeed.Name"/>.
+        /// Filters the result by <see cref="DataFeed.Name"/>. Only data feeds containing the filter as a
+        /// substring of their names will be returned. Case insensitive.
         /// </summary>
         public string Name { get; set; }
 
         /// <summary>
-        /// Filters the result by <see cref="DataFeed.Creator"/>.
+        /// Filters the result by <see cref="DataFeed.Creator"/>. Only data feeds containing the filter as a
+        /// substring of their creators will be returned. Case insensitive.
         /// </summary>
         public string Creator { get; set; }
 

sdk/metricsadvisor/Azure.AI.MetricsAdvisor/src/FeedbackQueryTimeMode.cs

@@ -19,12 +19,12 @@ public enum FeedbackQueryTimeMode
         None,
 
         /// <summary>
-        /// Filters feedbacks by its metric's timestamps.
+        /// Filters feedback by its metric's timestamps.
         /// </summary>
         MetricTimestamp,
 
         /// <summary>
-        /// Filters feedbacks by <see cref="MetricFeedback.CreatedOn"/>.
+        /// Filters feedback by <see cref="MetricFeedback.CreatedOn"/>.
         /// </summary>
         [CodeGenMember("FeedbackCreatedTime")]
         FeedbackCreatedOn

sdk/metricsadvisor/Azure.AI.MetricsAdvisor/src/GetDataFeedIngestionStatusesOptions.cs

@@ -11,9 +11,11 @@ namespace Azure.AI.MetricsAdvisor.Administration
     /// </summary>
     public class GetDataFeedIngestionStatusesOptions
     {
-        /// <summary> Initializes a new instance of the <see cref="GetDataFeedIngestionStatusesOptions"/> class. </summary>
-        /// <param name="startsOn"> The start point of time range to query data ingestion status. </param>
-        /// <param name="endsOn"> The end point of time range to query data ingestion status. </param>
+        /// <summary>
+        /// Initializes a new instance of the <see cref="GetDataFeedIngestionStatusesOptions"/> class.
+        /// </summary>
+        /// <param name="startsOn">The start point of time range to query data ingestion status.</param>
+        /// <param name="endsOn">The end point of time range to query data ingestion status.</param>
         public GetDataFeedIngestionStatusesOptions(DateTimeOffset startsOn, DateTimeOffset endsOn)
         {
             StartsOn = startsOn;

sdk/metricsadvisor/Azure.AI.MetricsAdvisor/src/GetHooksOptions.cs

@@ -10,7 +10,8 @@ namespace Azure.AI.MetricsAdvisor.Administration
     public class GetHooksOptions
     {
         /// <summary>
-        /// The name of the hook to filter on.
+        /// Filters the result by <see cref="NotificationHook.Name"/>. Only hooks containing the filter as a
+        /// substring of their names will be returned. Case insensitive.
         /// </summary>
         public string HookNameFilter { get; set; }
 

sdk/metricsadvisor/Azure.AI.MetricsAdvisor/src/GetMetricDimensionValuesOptions.cs

@@ -17,7 +17,8 @@ public GetMetricDimensionValuesOptions()
         }
 
         /// <summary>
-        /// The dimension value to be filtered.
+        /// Filters the result by dimension value. Only values containing the filter as a
+        /// substring will be returned. Case insensitive.
         /// </summary>
         public string DimensionValueFilter { get; set; }
 

sdk/metricsadvisor/Azure.AI.MetricsAdvisor/src/GetMetricEnrichmentStatusesOptions.cs

@@ -5,22 +5,31 @@
 
 namespace Azure.AI.MetricsAdvisor
 {
-    /// <summary> The GetEnrichmentStatusesOptions. </summary>
+    /// <summary>
+    /// The set of options that can be specified when calling <see cref="MetricsAdvisorClient.GetMetricEnrichmentStatuses"/> or
+    /// <see cref="MetricsAdvisorClient.GetMetricEnrichmentStatusesAsync"/> to configure the behavior of the request.
+    /// </summary>
     public class GetMetricEnrichmentStatusesOptions
     {
-        /// <summary> Initializes a new instance of <see cref="GetMetricEnrichmentStatusesOptions"/>. </summary>
-        /// <param name="startsOn"> the start point of time range to query anomaly detection status. </param>
-        /// <param name="endsOn"> the end point of time range to query anomaly detection status. </param>
+        /// <summary>
+        /// Initializes a new instance of <see cref="GetMetricEnrichmentStatusesOptions"/>.
+        /// </summary>
+        /// <param name="startsOn">The start point of time range to query enrichment status.</param>
+        /// <param name="endsOn">The end point of time range to query enrichment status.</param>
         public GetMetricEnrichmentStatusesOptions(DateTimeOffset startsOn, DateTimeOffset endsOn)
         {
             StartsOn = startsOn;
             EndsOn = endsOn;
         }
 
-        /// <summary> the start point of time range to query anomaly detection status. </summary>
+        /// <summary>
+        /// The start point of time range to query enrichment status.
+        /// </summary>
         public DateTimeOffset StartsOn { get; }
 
-        /// <summary> the end point of time range to query anomaly detection status. </summary>
+        /// <summary>
+        /// The end point of time range to query enrichment status.
+        /// </summary>
         public DateTimeOffset EndsOn { get; }
 
         /// <summary>

sdk/metricsadvisor/Azure.AI.MetricsAdvisor/src/MetricsAdvisorAdministrationClient.cs

@@ -14,7 +14,8 @@ namespace Azure.AI.MetricsAdvisor.Administration
     /// <summary>
     /// The client to use to connect to the Metrics Advisor Cognitive Service to handle administrative
     /// operations, configuring the behavior of the service. It provides the ability to create and manage
-    /// data feeds, anomaly detection configurations, anomaly alerting configurations and hooks.
+    /// data feeds, anomaly detection configurations, anomaly alerting configurations, hooks, and credential
+    /// entities.
     /// </summary>
     public class MetricsAdvisorAdministrationClient
     {

sdk/metricsadvisor/Azure.AI.MetricsAdvisor/src/MetricsAdvisorClient.cs

@@ -347,7 +347,7 @@ Page<MetricSeriesDefinition> NextPageFunc(string nextLink, int? pageSizeHint)
         /// <param name="metricId">The unique identifier of the <see cref="DataFeedMetric"/>.</param>
         /// <param name="options">The set of options used to configure the request's behavior.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
-        /// <returns>An <see cref="AsyncPageable{T}"/> containing the collection of <see cref="MetricSeriesData"/>s.</returns>
+        /// <returns>An <see cref="AsyncPageable{T}"/> containing the collection of <see cref="MetricSeriesData"/>.</returns>
         /// <exception cref="ArgumentNullException"><paramref name="metricId"/> or <paramref name="options"/> is null.</exception>
         /// <exception cref="ArgumentException"><paramref name="metricId"/> is empty or not a valid GUID.</exception>
         public virtual AsyncPageable<MetricSeriesData> GetMetricSeriesDataAsync(string metricId, GetMetricSeriesDataOptions options, CancellationToken cancellationToken = default)
@@ -385,7 +385,7 @@ async Task<Page<MetricSeriesData>> FirstPageFunc(int? pageSizeHint)
         /// <param name="metricId">The unique identifier of the <see cref="DataFeedMetric"/>.</param>
         /// <param name="options">The set of options used to configure the request's behavior.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
-        /// <returns>A <see cref="Pageable{T}"/> containing the collection of <see cref="MetricSeriesData"/>s.</returns>
+        /// <returns>A <see cref="Pageable{T}"/> containing the collection of <see cref="MetricSeriesData"/>.</returns>
         /// <exception cref="ArgumentNullException"><paramref name="metricId"/> or <paramref name="options"/> is null.</exception>
         /// <exception cref="ArgumentException"><paramref name="metricId"/> is empty or not a valid GUID.</exception>
         public virtual Pageable<MetricSeriesData> GetMetricSeriesData(string metricId, GetMetricSeriesDataOptions options, CancellationToken cancellationToken = default)
@@ -417,12 +417,16 @@ Page<MetricSeriesData> FirstPageFunc(int? pageSizeHint)
         }
 
         /// <summary>
-        ///
+        /// Gets the enrichment status for a given metric. Enrichment status is described by the service as the process
+        /// of detecting which data points of an ingested set of data can be classified as anomalies. Each status represents
+        /// a single data source ingestion.
         /// </summary>
-        /// <param name="metricId"></param>
-        /// <param name="options"></param>
+        /// <param name="metricId">The unique identifier of the <see cref="DataFeedMetric"/>.</param>
+        /// <param name="options">The set of options used to configure the request's behavior.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
-        /// <returns></returns>
+        /// <returns>An <see cref="AsyncPageable{T}"/> containing the collection of <see cref="EnrichmentStatus"/>.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="metricId"/> or <paramref name="options"/> is null.</exception>
+        /// <exception cref="ArgumentException"><paramref name="metricId"/> is empty or not a valid GUID.</exception>
         public virtual AsyncPageable<EnrichmentStatus> GetMetricEnrichmentStatusesAsync(string metricId, GetMetricEnrichmentStatusesOptions options, CancellationToken cancellationToken = default)
         {
             Argument.AssertNotNull(options, nameof(options));
@@ -470,12 +474,16 @@ async Task<Page<EnrichmentStatus>> NextPageFunc(string nextLink, int? pageSizeHi
         }
 
         /// <summary>
-        ///
+        /// Gets the enrichment status for a given metric. Enrichment status is described by the service as the process
+        /// of detecting which data points of an ingested set of data can be classified as anomalies. Each status represents
+        /// a single data source ingestion.
         /// </summary>
-        /// <param name="metricId"></param>
-        /// <param name="options"></param>
+        /// <param name="metricId">The unique identifier of the <see cref="DataFeedMetric"/>.</param>
+        /// <param name="options">The set of options used to configure the request's behavior.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
-        /// <returns></returns>
+        /// <returns>A <see cref="Pageable{T}"/> containing the collection of <see cref="EnrichmentStatus"/>.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="metricId"/> or <paramref name="options"/> is null.</exception>
+        /// <exception cref="ArgumentException"><paramref name="metricId"/> is empty or not a valid GUID.</exception>
         public virtual Pageable<EnrichmentStatus> GetMetricEnrichmentStatuses(string metricId, GetMetricEnrichmentStatusesOptions options, CancellationToken cancellationToken = default)
         {
             Argument.AssertNotNull(options, nameof(options));

sdk/metricsadvisor/Azure.AI.MetricsAdvisor/src/MetricsAdvisorClientsOptions.cs

@@ -2,13 +2,14 @@
 // Licensed under the MIT License.
 
 using System;
+using Azure.AI.MetricsAdvisor.Administration;
 using Azure.Core;
 
 namespace Azure.AI.MetricsAdvisor
 {
     /// <summary>
-    /// The set of options that can be specified when creating a <see cref="MetricsAdvisorClient" />
-    /// to configure its behavior.
+    /// The set of options that can be specified when creating a <see cref="MetricsAdvisorClient" /> or
+    /// a <see cref="MetricsAdvisorAdministrationClient"/> to configure its behavior.
     /// </summary>
     public class MetricsAdvisorClientsOptions : ClientOptions
     {

sdk/metricsadvisor/Azure.AI.MetricsAdvisor/src/Models/AlertTriggering/AnomalyAlertConfiguration.cs

@@ -10,8 +10,18 @@
 namespace Azure.AI.MetricsAdvisor.Models
 {
     /// <summary>
-    /// Defines the set of rules that must be satisfied by an anomaly before it can trigger an alert.
+    /// Detected anomalies won't trigger alerts by default, so an <see cref="AnomalyAlertConfiguration"/> must be
+    /// created if you want to be notified when an anomaly is detected. This configuration is applied to every set
+    /// of anomalies detected after a <see cref="DataFeed"/> ingestion, applying rules that select which of them
+    /// to include in the final alert.
     /// </summary>
+    /// <remarks>
+    /// In order to create an anomaly alert configuration, you must set up the property <see cref="Name"/> and
+    /// have at least one element in <see cref="MetricAlertConfigurations"/>, and pass this instance to the method
+    /// <see cref="MetricsAdvisorAdministrationClient.CreateAlertConfigurationAsync"/>. Note that, even if alerts are
+    /// triggered, you won't be notified about them unless you create a <see cref="NotificationHook"/> and pass its ID
+    /// to <see cref="IdsOfHooksToAlert"/>.
+    /// </remarks>
     [CodeGenModel("AnomalyAlertingConfiguration")]
     [CodeGenSuppress(nameof(AnomalyAlertConfiguration), typeof(string), typeof(IEnumerable<string>), typeof(IEnumerable<MetricAlertConfiguration>))]
     public partial class AnomalyAlertConfiguration
@@ -27,46 +37,58 @@ public AnomalyAlertConfiguration()
         }
 
         /// <summary>
-        /// The unique identifier of this <see cref="AnomalyAlertConfiguration"/>. Set by the service.
+        /// The unique identifier of this <see cref="AnomalyAlertConfiguration"/>.
         /// </summary>
+        /// <remarks>
+        /// If <c>null</c>, it means this instance has not been sent to the service to be created yet. This property
+        /// will be set by the service after creation.
+        /// </remarks>
         [CodeGenMember("AnomalyAlertingConfigurationId")]
         public string Id { get; }
 
         /// <summary>
         /// A custom name for this <see cref="AnomalyAlertConfiguration"/> to be displayed on fired alerts.
+        /// Alert configuration names must be unique for the same data feed.
         /// </summary>
         public string Name { get; set; }
 
         /// <summary>
-        /// The unique identifiers of the <see cref="NotificationHook"/>s that must be notified when an alert is
-        /// detected by this configuration.
+        /// The unique identifiers of the <see cref="NotificationHook"/>s to be notified when an alert is
+        /// fired by this configuration.
         /// </summary>
         [CodeGenMember("HookIds")]
         public IList<string> IdsOfHooksToAlert { get; }
 
         /// <summary>
-        /// The configurations that define which anomalies are eligible for triggering an alert.
+        /// The configurations that specify a set of rules a detected anomaly must satisfy to be included in
+        /// an alert.
         /// </summary>
+        /// <remarks>
+        /// If you're using at least two metric alert configurations, you need to set the property
+        /// <see cref="CrossMetricsOperator"/>.
+        /// </remarks>
         [CodeGenMember("MetricAlertingConfigurations")]
         public IList<MetricAlertConfiguration> MetricAlertConfigurations { get; }
 
         /// <summary>
-        /// The operator to be applied between <see cref="MetricAlertConfiguration"/>s in this
-        /// <see cref="AnomalyAlertConfiguration"/> instance. This property must be set if more than one
-        /// configuration is defined in <see cref="MetricAlertConfigurations"/>.
+        /// The operator to be applied between <see cref="MetricAlertConfiguration"/>s in this instance.
+        /// This property must be set if at least two configurations are defined in <see cref="MetricAlertConfigurations"/>.
         /// </summary>
         public MetricAlertConfigurationsOperator? CrossMetricsOperator { get; set; }
 
         /// <summary>
-        /// A description of the <see cref="AnomalyAlertConfiguration"/>.
+        /// A description of this <see cref="AnomalyAlertConfiguration"/>. Defaults to an empty string.
         /// </summary>
+        /// <remarks>
+        /// If set to null during an update operation, this property is set to its default value.
+        /// </remarks>
         public string Description { get; set; }
 
         /// <summary>
-        /// By default, an incident only triggers a single alert, regardless of how many anomalies
-        /// it contains. This property allows this alert to be split into multiple ones. Each element
-        /// in this list must hold a dimension name, and it creates a new alert from the original one
-        /// if the corresponding dimension is part of current incident.
+        /// By default, a set of ingested data points can only trigger a single alert, regardless of
+        /// how many anomalies it contains. This property allows this alert to be split into multiple ones.
+        /// Each element in this list must hold a dimension name, and a separate alert is fired for every
+        /// specified dimension. The dimensions not specified in this list will be grouped in a single alert.
         /// </summary>
         [CodeGenMember("SplitAlertByDimensions")]
         public IList<string> DimensionsToSplitAlert { get; }