[Metrics Advisor] Add remaining docstrings

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

@@ -472,12 +472,14 @@ public virtual Response DeleteDataFeed(string dataFeedId, CancellationToken canc
             }
         }
 
-        // TODODOCS
         /// <summary>
+        /// Gets the ingestion progress for data being ingested to a given data feed.
         /// </summary>
-        /// <param name="dataFeedId"></param>
-        /// <param name="cancellationToken"></param>
-        /// <returns></returns>
+        /// <param name="dataFeedId">The unique identifier of the <see cref="DataFeed"/>.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
+        /// <returns>
+        /// A <see cref="Response{T}"/> containing the result of the operation. The result is a <see cref="DataFeedIngestionProgress"/> instance.
+        /// </returns>
         public virtual async Task<Response<DataFeedIngestionProgress>> GetDataFeedIngestionProgressAsync(string dataFeedId, CancellationToken cancellationToken = default)
         {
             Guid dataFeedGuid = ClientCommon.ValidateGuid(dataFeedId, nameof(dataFeedId));
@@ -495,12 +497,14 @@ public virtual async Task<Response<DataFeedIngestionProgress>> GetDataFeedIngest
             }
         }
 
-        // TODODOCS.
         /// <summary>
+        /// Gets the ingestion progress for data being ingested to a given data feed.
         /// </summary>
-        /// <param name="dataFeedId"></param>
-        /// <param name="cancellationToken"></param>
-        /// <returns></returns>
+        /// <param name="dataFeedId">The unique identifier of the <see cref="DataFeed"/>.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
+        /// <returns>
+        /// A <see cref="Response{T}"/> containing the result of the operation. The result is a <see cref="DataFeedIngestionProgress"/> instance.
+        /// </returns>
         public virtual Response<DataFeedIngestionProgress> GetDataFeedIngestionProgress(string dataFeedId, CancellationToken cancellationToken = default)
         {
             Guid dataFeedGuid = ClientCommon.ValidateGuid(dataFeedId, nameof(dataFeedId));
@@ -518,14 +522,17 @@ public virtual Response<DataFeedIngestionProgress> GetDataFeedIngestionProgress(
             }
         }
 
-        // TODODOCS.
         /// <summary>
+        /// Resets the data ingestion status for a given data feed to back-fill data. This can be useful to fix a failed ingestion or override the existing data.
+        /// Anomaly detection is re-triggered on selected range only.
         /// </summary>
-        /// <param name="dataFeedId"></param>
-        /// <param name="startTime"></param>
-        /// <param name="endTime"></param>
-        /// <param name="cancellationToken"></param>
-        /// <returns></returns>
+        /// <param name="dataFeedId">The unique identifier of the <see cref="DataFeed"/>.</param>
+        /// <param name="startTime">The inclusive data back-fill time range.</param>
+        /// <param name="endTime">The exclusive data back-fill time range.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
+        /// <returns>
+        /// A <see cref="Response"/> containing the result of the operation.
+        /// </returns>
         public virtual async Task<Response> RefreshDataFeedIngestionAsync(string dataFeedId, DateTimeOffset startTime, DateTimeOffset endTime, CancellationToken cancellationToken = default)
         {
             Guid dataFeedGuid = ClientCommon.ValidateGuid(dataFeedId, nameof(dataFeedId));
@@ -545,14 +552,17 @@ public virtual async Task<Response> RefreshDataFeedIngestionAsync(string dataFee
             }
         }
 
-        // TODODOCS.
         /// <summary>
+        /// Resets the data ingestion status for a given data feed to back-fill data. This can be useful to fix a failed ingestion or override the existing data.
+        /// Anomaly detection is re-triggered on selected range only.
         /// </summary>
-        /// <param name="dataFeedId"></param>
-        /// <param name="startTime"></param>
-        /// <param name="endTime"></param>
-        /// <param name="cancellationToken"></param>
-        /// <returns></returns>
+        /// <param name="dataFeedId">The unique identifier of the <see cref="DataFeed"/>.</param>
+        /// <param name="startTime">The inclusive data back-fill time range.</param>
+        /// <param name="endTime">The exclusive data back-fill time range.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
+        /// <returns>
+        /// A <see cref="Response"/> containing the result of the operation.
+        /// </returns>
         public virtual Response RefreshDataFeedIngestion(string dataFeedId, DateTimeOffset startTime, DateTimeOffset endTime, CancellationToken cancellationToken = default)
         {
             Guid dataFeedGuid = ClientCommon.ValidateGuid(dataFeedId, nameof(dataFeedId));
@@ -572,9 +582,13 @@ public virtual Response RefreshDataFeedIngestion(string dataFeedId, DateTimeOffs
             }
         }
 
-        // TODODOCS.
         /// <summary>
+        /// Gets the ingestion status for data being ingested to a given data feed.
         /// </summary>
+        /// <param name="dataFeedId">The unique identifier of the <see cref="DataFeed"/>.</param>
+        /// <param name="options">An optional 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="DataFeedIngestionStatus"/>.</returns>
         public virtual AsyncPageable<DataFeedIngestionStatus> GetDataFeedIngestionStatusesAsync(string dataFeedId, GetDataFeedIngestionStatusesOptions options, CancellationToken cancellationToken = default)
         {
             Guid dataFeedGuid = ClientCommon.ValidateGuid(dataFeedId, nameof(dataFeedId));
@@ -621,9 +635,13 @@ async Task<Page<DataFeedIngestionStatus>> NextPageFunc(string nextLink, int? pag
             return PageableHelpers.CreateAsyncEnumerable(FirstPageFunc, NextPageFunc);
         }
 
-        // TODODOCS.
         /// <summary>
+        /// Gets the ingestion status for data being ingested to a given data feed.
         /// </summary>
+        /// <param name="dataFeedId">The unique identifier of the <see cref="DataFeed"/>.</param>
+        /// <param name="options">An optional 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="Pageable{T}"/> containing the collection of <see cref="DataFeedIngestionStatus"/>.</returns>
         public virtual Pageable<DataFeedIngestionStatus> GetDataFeedIngestionStatuses(string dataFeedId, GetDataFeedIngestionStatusesOptions options, CancellationToken cancellationToken = default)
         {
             Guid dataFeedGuid = ClientCommon.ValidateGuid(dataFeedId, nameof(dataFeedId));

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

@@ -1013,9 +1013,15 @@ Page<AnomalyIncident> NextPageFunc(string nextLink, int? pageSizeHint)
             return PageableHelpers.CreateEnumerable(FirstPageFunc, NextPageFunc);
         }
 
-        // TODODOCS.
         /// <summary>
+        /// Gets the automatic suggestions for likely root causes of an incident.
         /// </summary>
+        /// <param name="detectionConfigurationId">The unique identifier of the <see cref="MetricAnomalyAlertConfiguration"/>.</param>
+        /// <param name="incidentId">The unique identifier of the <see cref="AnomalyIncident"/>.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
+        /// <returns>A collection of <see cref="IncidentRootCause"/>s for the specified alert configuration and incident.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="detectionConfigurationId"/> or <paramref name="incidentId"/> is null.</exception>
+        /// <exception cref="ArgumentException"><paramref name="detectionConfigurationId"/> or <paramref name="incidentId"/> is empty; or <paramref name="detectionConfigurationId"/> is not a valid GUID.</exception>
         public virtual async Task<Response<IReadOnlyList<IncidentRootCause>>> GetIncidentRootCausesAsync(string detectionConfigurationId, string incidentId, CancellationToken cancellationToken = default)
         {
             Argument.AssertNotNullOrEmpty(detectionConfigurationId, nameof(detectionConfigurationId));
@@ -1039,7 +1045,14 @@ public virtual async Task<Response<IReadOnlyList<IncidentRootCause>>> GetInciden
         }
 
         /// <summary>
+        /// Gets the automatic suggestions for likely root causes of an incident.
         /// </summary>
+        /// <param name="detectionConfigurationId">The unique identifier of the <see cref="MetricAnomalyAlertConfiguration"/>.</param>
+        /// <param name="incidentId">The unique identifier of the <see cref="AnomalyIncident"/>.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
+        /// <returns>A collection of <see cref="IncidentRootCause"/>s for the specified alert configuration and incident.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="detectionConfigurationId"/> or <paramref name="incidentId"/> is null.</exception>
+        /// <exception cref="ArgumentException"><paramref name="detectionConfigurationId"/> or <paramref name="incidentId"/> is empty; or <paramref name="detectionConfigurationId"/> is not a valid GUID.</exception>
         public virtual Response<IReadOnlyList<IncidentRootCause>> GetIncidentRootCauses(string detectionConfigurationId, string incidentId, CancellationToken cancellationToken = default)
         {
             Argument.AssertNotNullOrEmpty(detectionConfigurationId, nameof(detectionConfigurationId));
@@ -1188,15 +1201,14 @@ Page<string> NextPageFunc(string nextLink, int? pageSizeHint)
 
         // TODODOCS.
         /// <summary>
-        /// Gets data about the data points present in the specified set of time series.
-        /// <see cref="MetricAnomalyAlertConfiguration"/>.
+        /// Query series enriched by anomaly detection.
         /// </summary>
-        /// <param name="seriesKeys">The name of the dimension.</param>
+        /// <param name="seriesKeys">The detection series keys.</param>
         /// <param name="detectionConfigurationId">The unique identifier of the <see cref="MetricAnomalyAlertConfiguration"/>.</param>
-        /// <param name="startTime">Filters the result. Only data points ingested after this point in time, in UTC, will be returned.</param>
-        /// <param name="endTime">Filters the result. Only data points ingested after this point in time, in UTC, will be returned.</param>
+        /// <param name="startTime">Filters the result. Only data points after this point in time, in UTC, will be returned.</param>
+        /// <param name="endTime">Filters the result. Only data points after this point in time, in UTC, will be returned.</param>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
-        /// <returns>A collection containing the values the specified dimension assumed for anomalous data points. Items are unique.</returns>
+        /// <returns>A collection of <see cref="MetricEnrichedSeriesData"/>.</returns>
         /// <exception cref="ArgumentNullException"><paramref name="seriesKeys"/> or <paramref name="detectionConfigurationId"/> is null.</exception>
         /// <exception cref="ArgumentException"><paramref name="seriesKeys"/> or <paramref name="detectionConfigurationId"/> is empty; or <paramref name="detectionConfigurationId"/> is not a valid GUID.</exception>
         public virtual async Task<Response<IReadOnlyList<MetricEnrichedSeriesData>>> GetMetricEnrichedSeriesDataAsync(IEnumerable<DimensionKey> seriesKeys, string detectionConfigurationId, DateTimeOffset startTime, DateTimeOffset endTime, CancellationToken cancellationToken = default)
@@ -1224,7 +1236,16 @@ public virtual async Task<Response<IReadOnlyList<MetricEnrichedSeriesData>>> Get
         }
 
         /// <summary>
+        /// Query series enriched by anomaly detection.
         /// </summary>
+        /// <param name="seriesKeys">The deection series keys.</param>
+        /// <param name="detectionConfigurationId">The unique identifier of the <see cref="MetricAnomalyAlertConfiguration"/>.</param>
+        /// <param name="startTime">Filters the result. Only data points after this point in time, in UTC, will be returned.</param>
+        /// <param name="endTime">Filters the result. Only data points after this point in time, in UTC, will be returned.</param>
+        /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
+        /// <returns>A collection of <see cref="MetricEnrichedSeriesData"/>.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="seriesKeys"/> or <paramref name="detectionConfigurationId"/> is null.</exception>
+        /// <exception cref="ArgumentException"><paramref name="seriesKeys"/> or <paramref name="detectionConfigurationId"/> is empty; or <paramref name="detectionConfigurationId"/> is not a valid GUID.</exception>
         public virtual Response<IReadOnlyList<MetricEnrichedSeriesData>> GetMetricEnrichedSeriesData(IEnumerable<DimensionKey> seriesKeys, string detectionConfigurationId, DateTimeOffset startTime, DateTimeOffset endTime, CancellationToken cancellationToken = default)
         {
             Argument.AssertNotNullOrEmpty(seriesKeys, nameof(seriesKeys)); // TODO: add validation for seriesKeys.Dimension?
@@ -1479,7 +1500,6 @@ Page<DataAnomaly> NextPageFunc(string nextLink, int? pageSizeHint)
             return PageableHelpers.CreateEnumerable(FirstPageFunc, NextPageFunc);
         }
 
-        // TODODOCS: double check if reasoning is right. Alert configurations do not generate incidents.
         /// <summary>
         /// Given an alert, gets the incidents associated with the anomalies that triggered it. The associated
         /// <see cref="AnomalyAlertConfiguration"/> must also be specified.

sdk/metricsadvisor/Azure.AI.MetricsAdvisor/src/Models/AnomalyAlert/MetricAnomalyAlertScope.cs

@@ -25,14 +25,16 @@ internal MetricAnomalyAlertScope(MetricAnomalyAlertScopeType scopeType, Dimensio
         public MetricAnomalyAlertScopeType ScopeType { get; }
 
         /// <summary>
-        /// The key that identifies the group of fixed time series that constitutes this scope. A subset of the possible
-        /// dimensions of the associated data feed must be set. This property is set when <see cref="ScopeType"/>
-        /// is <see cref="MetricAnomalyAlertScopeType.SeriesGroup"/>.
+        /// Alerts will only be triggered for anomalies in specific dimensions of the series group.
+        /// The number of specified dimensions should be smaller than the total number dimensions.
+        /// This property is set when <see cref="ScopeType"/> is <see cref="MetricAnomalyAlertScopeType.SeriesGroup"/>.
         /// </summary>
         public DimensionKey SeriesGroupInScope { get; }
 
-        // TODODOCS.
         /// <summary>
+        /// Alerts will only be triggered for anomalies in the top N series.
+        /// Specify the number of timestamps to take into account, and how many anomalies must be in them to send the alert.
+        /// This property is set when <see cref="ScopeType"/> is <see cref="MetricAnomalyAlertScopeType.TopN"/>.
         /// </summary>
         public TopNGroupScope TopNGroupInScope { get; }
 
@@ -47,7 +49,8 @@ public static MetricAnomalyAlertScope GetScopeForWholeSeries() =>
         /// <summary>
         /// Creates a <see cref="MetricAnomalyAlertScope"/> instance that has a fixed group of time series as the scope.
         /// </summary>
-        /// <param name="seriesGroupKey">The key that identifies the group of fixed time series that constitutes the scope. A subset of the possible dimensions of the associated data feed must be set.</param>
+        /// <param name="seriesGroupKey">The key that identifies the group of fixed time series that constitutes the scope.
+        /// A subset of the possible dimensions of the associated data feed must be set.</param>
         /// <returns>A new <see cref="MetricAnomalyAlertScope"/> instance.</returns>
         /// <exception cref="ArgumentNullException"><paramref name="seriesGroupKey"/> is null.</exception>
         public static MetricAnomalyAlertScope GetScopeForSeriesGroup(DimensionKey seriesGroupKey)
@@ -57,9 +60,10 @@ public static MetricAnomalyAlertScope GetScopeForSeriesGroup(DimensionKey series
             return new MetricAnomalyAlertScope(MetricAnomalyAlertScopeType.SeriesGroup, seriesGroupKey, topNGroupInScope: default);
         }
 
-        // TODODOCS.
         /// <summary>
+        /// Creates a <see cref="MetricAnomalyAlertScope"/> instance in which alerts will only be triggered for anomalies in the top N series.
         /// </summary>
+        /// <param name="topNGroup">Specify the number of timestamps to take into account, and how many anomalies must be in them to send the alert.</param>
         /// <exception cref="ArgumentNullException"><paramref name="topNGroup"/> is null.</exception>
         public static MetricAnomalyAlertScope GetScopeForTopNGroup(TopNGroupScope topNGroup)
         {

sdk/metricsadvisor/Azure.AI.MetricsAdvisor/src/Models/AnomalyAlert/MetricAnomalyAlertScopeType.cs

@@ -12,19 +12,20 @@ namespace Azure.AI.MetricsAdvisor.Models
     public readonly partial struct MetricAnomalyAlertScopeType
     {
         /// <summary>
-        /// The scope is all time series within the associated metric.
+        /// Alerts will be triggered for anomalies in all series within the metric.
         /// </summary>
         [CodeGenMember("All")]
         public static MetricAnomalyAlertScopeType WholeSeries { get; } = new MetricAnomalyAlertScopeType(WholeSeriesValue);
 
         /// <summary>
-        /// The scope is a fixed group of time series.
+        /// Alerts will only be triggered for anomalies in specific dimensions of the series group.
         /// </summary>
         [CodeGenMember("Dimension")]
         public static MetricAnomalyAlertScopeType SeriesGroup { get; } = new MetricAnomalyAlertScopeType(SeriesGroupValue);
 
-        // TODODOCS.
         /// <summary>
+        /// Alerts will only be triggered for anomalies in the top N series.
+        /// You can set parameters to specify the number of timestamps to take into account, and how many anomalies must be in them to send the alert.
         /// </summary>
         public static MetricAnomalyAlertScopeType TopN { get; } = new MetricAnomalyAlertScopeType(TopNValue);
     }

sdk/metricsadvisor/Azure.AI.MetricsAdvisor/src/Models/AnomalyAlert/TopNGroupScope.cs

@@ -5,8 +5,10 @@
 
 namespace Azure.AI.MetricsAdvisor.Models
 {
-    // TODODOCS: this whole class needs clarification.
     /// <summary>
+    /// Alerts will only be triggered for anomalies in the top N series.
+    /// Use <see cref="Top"/> to specify the number of timestamps to take into account, and <see cref="MinimumTopCount"/>
+    /// to specify how many anomalies must be in them to send the alert.
     /// </summary>
     public partial class TopNGroupScope
     {
@@ -27,14 +29,17 @@ public TopNGroupScope(int top, int period, int minimumTopCount)
         }
 
         /// <summary>
+        /// The number of timestamps to take into account.
         /// </summary>
         public int Top { get; }
 
         /// <summary>
+        /// The number of items a period contains.
         /// </summary>
         public int Period { get; }
 
         /// <summary>
+        /// The number of anomalies that must be in the specified <see cref="Top"/> number of timestamps to send an alert.
         /// </summary>
         [CodeGenMember("MinTopCount")]
         public int MinimumTopCount { get; }