Update XML docs for public Monitor Query APIs (Azure#38902)

* Update XML docs for public Monitor Query APIs

* Update parameter descriptions

* Fix typo

Author: scottaddie

sdk/monitor/Azure.Monitor.Query/src/LogsQueryClient.cs

@@ -79,7 +79,7 @@ public LogsQueryClient(Uri endpoint, TokenCredential credential, LogsQueryClient
         }
 
         /// <summary>
-        /// Initializes a new instance of <see cref="LogsQueryClient"/> for mocking.
+        /// Creates an instance of <see cref="LogsQueryClient"/> to support <see href="https://aka.ms/azsdk/net/mocking">mocking</see>.
         /// </summary>
         protected LogsQueryClient()
         {
@@ -113,12 +113,15 @@ protected LogsQueryClient()
         /// </code>
         /// </example>
         /// </summary>
-        /// <param name="workspaceId">The workspace id to include in the query (<c>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</c>).</param>
-        /// <param name="query">The Kusto query to execute.</param>
-        /// <param name="timeRange">The timespan over which to query data. Logs will be filtered to include entries produced starting at <c>Now - timeSpan</c>. </param>
+        /// <param name="workspaceId">The workspace ID to include in the query (<c>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</c>).</param>
+        /// <param name="query">The Kusto query to fetch the logs.</param>
+        /// <param name="timeRange">The time period for which the logs should be looked up.</param>
         /// <param name="options">The <see cref="LogsQueryOptions"/> to configure the query.</param>
         /// <param name="cancellationToken">The <see cref="CancellationToken"/> to use.</param>
         /// <returns>Query results mapped to a type <typeparamref name="T"/>.</returns>
+        /// <remarks>
+        /// When the <paramref name="timeRange"/> argument is <see cref="QueryTimeRange.All"/> and the <paramref name="query"/> argument contains a time range filter, the underlying service uses the time range specified in <paramref name="query"/>.
+        /// </remarks>
         public virtual Response<IReadOnlyList<T>> QueryWorkspace<T>(string workspaceId, string query, QueryTimeRange timeRange, LogsQueryOptions options = null, CancellationToken cancellationToken = default)
         {
             Response<LogsQueryResult> response = QueryWorkspace(workspaceId, query, timeRange, options, cancellationToken);
@@ -149,12 +152,15 @@ public virtual Response<IReadOnlyList<T>> QueryWorkspace<T>(string workspaceId,
         /// </code>
         /// </example>
         /// </summary>
-        /// <param name="workspaceId">The workspace id to include in the query (<c>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</c>).</param>
-        /// <param name="query">The Kusto query to execute.</param>
-        /// <param name="timeRange">The timespan over which to query data. Logs will be filtered to include entries produced starting at <c>Now - timeSpan</c>. </param>
+        /// <param name="workspaceId">The workspace ID to include in the query (<c>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</c>).</param>
+        /// <param name="query">The Kusto query to fetch the logs.</param>
+        /// <param name="timeRange">The time period for which the logs should be looked up.</param>
         /// <param name="options">The <see cref="LogsQueryOptions"/> to configure the query.</param>
         /// <param name="cancellationToken">The <see cref="CancellationToken"/> to use.</param>
         /// <returns>Query results mapped to a type <typeparamref name="T"/>.</returns>
+        /// <remarks>
+        /// When the <paramref name="timeRange"/> argument is <see cref="QueryTimeRange.All"/> and the <paramref name="query"/> argument contains a time range filter, the underlying service uses the time range specified in <paramref name="query"/>.
+        /// </remarks>
         public virtual async Task<Response<IReadOnlyList<T>>> QueryWorkspaceAsync<T>(string workspaceId, string query, QueryTimeRange timeRange, LogsQueryOptions options = null, CancellationToken cancellationToken = default)
         {
             Response<LogsQueryResult> response = await QueryWorkspaceAsync(workspaceId, query, timeRange, options, cancellationToken).ConfigureAwait(false);
@@ -165,12 +171,15 @@ public virtual async Task<Response<IReadOnlyList<T>>> QueryWorkspaceAsync<T>(str
         /// <summary>
         /// Executes the logs query.
         /// </summary>
-        /// <param name="workspaceId">The workspace id to include in the query (<c>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</c>).</param>
-        /// <param name="query">The Kusto query to execute.</param>
-        /// <param name="timeRange">The timespan over which to query data. Logs will be filtered to include entries produced starting at <c>Now - timeSpan</c>. </param>
+        /// <param name="workspaceId">The workspace ID to include in the query (<c>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</c>).</param>
+        /// <param name="query">The Kusto query to fetch the logs.</param>
+        /// <param name="timeRange">The time period for which the logs should be looked up.</param>
         /// <param name="options">The <see cref="LogsQueryOptions"/> to configure the query.</param>
         /// <param name="cancellationToken">The <see cref="CancellationToken"/> to use.</param>
         /// <returns>The <see cref="LogsQueryResult"/> containing the query results.</returns>
+        /// <remarks>
+        /// When the <paramref name="timeRange"/> argument is <see cref="QueryTimeRange.All"/> and the <paramref name="query"/> argument contains a time range filter, the underlying service uses the time range specified in <paramref name="query"/>.
+        /// </remarks>
         public virtual Response<LogsQueryResult> QueryWorkspace(string workspaceId, string query, QueryTimeRange timeRange, LogsQueryOptions options = null, CancellationToken cancellationToken = default)
         {
             using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(LogsQueryClient)}.{nameof(QueryWorkspace)}");
@@ -189,12 +198,15 @@ public virtual Response<LogsQueryResult> QueryWorkspace(string workspaceId, stri
         /// <summary>
         /// Executes the logs query.
         /// </summary>
-        /// <param name="workspaceId">The workspace id to include in the query (<c>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</c>).</param>
-        /// <param name="query">The Kusto query to execute.</param>
-        /// <param name="timeRange">The timespan over which to query data. Logs will be filtered to include entries produced starting at <c>Now - timeSpan</c>. </param>
+        /// <param name="workspaceId">The workspace ID to include in the query (<c>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</c>).</param>
+        /// <param name="query">The Kusto query to fetch the logs.</param>
+        /// <param name="timeRange">The time period for which the logs should be looked up.</param>
         /// <param name="options">The <see cref="LogsQueryOptions"/> to configure the query.</param>
         /// <param name="cancellationToken">The <see cref="CancellationToken"/> to use.</param>
         /// <returns>The <see cref="LogsQueryResult"/> with the query results.</returns>
+        /// <remarks>
+        /// When the <paramref name="timeRange"/> argument is <see cref="QueryTimeRange.All"/> and the <paramref name="query"/> argument contains a time range filter, the underlying service uses the time range specified in <paramref name="query"/>.
+        /// </remarks>
         public virtual async Task<Response<LogsQueryResult>> QueryWorkspaceAsync(string workspaceId, string query, QueryTimeRange timeRange, LogsQueryOptions options = null, CancellationToken cancellationToken = default)
         {
             using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(LogsQueryClient)}.{nameof(QueryWorkspace)}");
@@ -344,7 +356,7 @@ public virtual async Task<Response<LogsBatchQueryResultCollection>> QueryBatchAs
         /// </code>
         /// </example>
         /// </summary>
-        /// <param name="resourceId"> The resourceId where the query should be executed. </param>
+        /// <param name="resourceId"> The Azure resource ID where the query should be executed. </param>
         /// <param name="query"> The Kusto query to fetch the logs. </param>
         /// <param name="timeRange"> The time period for which the logs should be looked up. </param>
         /// <param name="options">The <see cref="LogsQueryOptions"/> to configure the query.</param>
@@ -383,12 +395,15 @@ public virtual Response<IReadOnlyList<T>> QueryResource<T>(ResourceIdentifier re
         /// </code>
         /// </example>
         /// </summary>
-        /// <param name="resourceId"> The resourceId where the query should be executed. </param>
+        /// <param name="resourceId"> The Azure resource ID where the query should be executed. </param>
         /// <param name="query"> The Kusto query to fetch the logs. </param>
         /// <param name="timeRange"> The time period for which the logs should be looked up. </param>
         /// <param name="options">The <see cref="LogsQueryOptions"/> to configure the query.</param>
         /// <param name="cancellationToken">The <see cref="CancellationToken"/> to use.</param>
         /// <returns>The logs matching the query.</returns>
+        /// <remarks>
+        /// When the <paramref name="timeRange"/> argument is <see cref="QueryTimeRange.All"/> and the <paramref name="query"/> argument contains a time range filter, the underlying service uses the time range specified in <paramref name="query"/>.
+        /// </remarks>
         public virtual async Task<Response<IReadOnlyList<T>>> QueryResourceAsync<T>(ResourceIdentifier resourceId, string query, QueryTimeRange timeRange, LogsQueryOptions options = null, CancellationToken cancellationToken = default)
         {
             Response<LogsQueryResult> response = await QueryResourceAsync(resourceId, query, timeRange, options, cancellationToken).ConfigureAwait(false);
@@ -422,12 +437,15 @@ public virtual async Task<Response<IReadOnlyList<T>>> QueryResourceAsync<T>(Reso
         /// </code>
         /// </example>
         /// </summary>
-        /// <param name="resourceId"> The resourceId where the query should be executed. </param>
+        /// <param name="resourceId"> The Azure resource ID where the query should be executed. </param>
         /// <param name="query"> The Kusto query to fetch the logs. </param>
         /// <param name="timeRange"> The time period for which the logs should be looked up. </param>
         /// <param name="options">The <see cref="LogsQueryOptions"/> to configure the query.</param>
         /// <param name="cancellationToken">The <see cref="CancellationToken"/> to use.</param>
         /// <returns>The logs matching the query.</returns>
+        /// <remarks>
+        /// When the <paramref name="timeRange"/> argument is <see cref="QueryTimeRange.All"/> and the <paramref name="query"/> argument contains a time range filter, the underlying service uses the time range specified in <paramref name="query"/>.
+        /// </remarks>
         public virtual Response<LogsQueryResult> QueryResource(ResourceIdentifier resourceId, string query, QueryTimeRange timeRange, LogsQueryOptions options = null, CancellationToken cancellationToken = default)
         {
             using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(LogsQueryClient)}.{nameof(QueryResource)}");
@@ -471,12 +489,15 @@ public virtual Response<LogsQueryResult> QueryResource(ResourceIdentifier resour
         /// </code>
         /// </example>
         /// </summary>
-        /// <param name="resourceId"> The resourceId where the query should be executed. </param>
+        /// <param name="resourceId"> The Azure resource ID where the query should be executed. </param>
         /// <param name="query"> The Kusto query to fetch the logs. </param>
         /// <param name="timeRange"> The time period for which the logs should be looked up. </param>
         /// <param name="options">The <see cref="LogsQueryOptions"/> to configure the query.</param>
         /// <param name="cancellationToken">The <see cref="CancellationToken"/> to use.</param>
         /// <returns>The logs matching the query.</returns>
+        /// <remarks>
+        /// When the <paramref name="timeRange"/> argument is <see cref="QueryTimeRange.All"/> and the <paramref name="query"/> argument contains a time range filter, the underlying service uses the time range specified in <paramref name="query"/>.
+        /// </remarks>
         public virtual async Task<Response<LogsQueryResult>> QueryResourceAsync(ResourceIdentifier resourceId, string query, QueryTimeRange timeRange, LogsQueryOptions options = null, CancellationToken cancellationToken = default)
         {
             using DiagnosticScope scope = _clientDiagnostics.CreateScope($"{nameof(LogsQueryClient)}.{nameof(QueryResource)}");

sdk/monitor/Azure.Monitor.Query/src/LogsQueryOptions.cs

@@ -38,7 +38,7 @@ public class LogsQueryOptions
         /// </para>
         /// <para>
         /// Although this collection cannot be set, it can be modified.
-        /// See <see href="https://docs.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/object-and-collection-initializers#object-initializers-with-collection-read-only-property-initialization">Object initializers with collection read-only property initialization</see>.
+        /// See <see href="https://learn.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/object-and-collection-initializers#object-initializers-with-collection-read-only-property-initialization">Object initializers with collection read-only property initialization</see>.
         /// </para>
         /// </summary>
         public IList<string> AdditionalWorkspaces { get; } = new ChangeTrackingList<string>();

sdk/monitor/Azure.Monitor.Query/src/MetricsQueryClient.cs

@@ -70,7 +70,7 @@ public MetricsQueryClient(Uri endpoint, TokenCredential credential, MetricsQuery
         }
 
         /// <summary>
-        /// Initializes a new instance of <see cref="MetricsQueryClient"/> for mocking.
+        /// Creates an instance of <see cref="MetricsQueryClient"/> to support <see href="https://aka.ms/azsdk/net/mocking">mocking</see>.
         /// </summary>
         protected MetricsQueryClient()
         {

sdk/monitor/Azure.Monitor.Query/src/Models/MonitorQueryModelFactory.cs

@@ -14,14 +14,16 @@
 namespace Azure.Monitor.Query.Models
 {
     /// <summary>
-    /// Model factory that enables mocking for the MetricsQueryResult class.
+    /// Model factory that enables mocking for public model types.
     /// </summary>
     public static partial class MonitorQueryModelFactory
     {
-        /// <summary> Enables the user to create an instance of a <see cref="MetricsQueryResult"/>. </summary>
+        /// <summary>
+        /// Creates an instance of <see cref="MetricsQueryResult"/> to support <see href="https://aka.ms/azsdk/net/mocking">mocking</see>.
+        /// </summary>
         /// <param name="cost"> The integer value representing the relative cost of the query. </param>
         /// <param name="timespan"> The timespan for which the data was retrieved. Its value consists of two datetimes concatenated, separated by &apos;/&apos;.  This may be adjusted in the future and returned back from what was originally requested. </param>
-        /// <param name="granularity"> The interval (window size) for which the metric data was returned in.  This may be adjusted in the future and returned back from what was originally requested.  This is not present if a metadata request was made. </param>
+        /// <param name="granularity"> The interval (window size) for which the metric data was returned in. This may be adjusted in the future and returned back from what was originally requested.  This is not present if a metadata request was made. </param>
         /// <param name="namespace"> The namespace of the metrics being queried. </param>
         /// <param name="resourceRegion"> The region of the resource being queried for metrics. </param>
         /// <param name="metrics"> The value of the collection. </param>
@@ -31,7 +33,7 @@ public static MetricsQueryResult MetricsQueryResult(int? cost, string timespan,
         }
 
         /// <summary>
-        /// Enables the user to create an instance of a <see cref="MetricResult"/>.
+        /// Creates an instance of <see cref="Models.MetricResult"/> to support <see href="https://aka.ms/azsdk/net/mocking">mocking</see>.
         /// </summary>
         /// <param name="id"> The metric ID. </param>
         /// <param name="resourceType"> The resource type of the metric resource. </param>
@@ -44,10 +46,10 @@ public static MetricResult MetricResult(string id, string resourceType, string n
         }
 
         /// <summary>
-        /// Enables the user to create an instance of a <see cref="MetricTimeSeriesElement"/>.
+        /// Creates an instance of <see cref="Models.MetricTimeSeriesElement"/> to support <see href="https://aka.ms/azsdk/net/mocking">mocking</see>.
+        /// </summary>
         /// <param name="metadataValues"> A dictionary comprised of metric metadata values. </param>
         /// <param name="values"> A list of <see cref="Models.MetricValue"/> elements. </param>
-        /// </summary>
         public static MetricTimeSeriesElement MetricTimeSeriesElement(IReadOnlyDictionary<string, string> metadataValues, IEnumerable<MetricValue> values)
         {
             var metadataValueList = new List<MetadataValue>();
@@ -59,7 +61,9 @@ public static MetricTimeSeriesElement MetricTimeSeriesElement(IReadOnlyDictionar
             return new MetricTimeSeriesElement(metadataValueList, values.ToList());
         }
 
-        /// <summary> Initializes a new instance of MetricValue. </summary>
+        /// <summary>
+        /// Creates an instance of <see cref="Models.MetricValue"/> to support <see href="https://aka.ms/azsdk/net/mocking">mocking</see>.
+        /// </summary>
         /// <param name="timeStamp"> The timestamp for the metric value in ISO 8601 format. </param>
         /// <param name="average"> The average value in the time range. </param>
         /// <param name="minimum"> The least value in the time range. </param>
@@ -71,8 +75,10 @@ public static MetricValue MetricValue(DateTimeOffset timeStamp = default, double
             return new MetricValue(timeStamp, average, minimum, maximum, total, count);
         }
 
-        /// <summary> Enables the user to create an instance of a <see cref="LogsQueryResult"/>. </summary>
-        /// <param name="allTables"> The list of tables, columns and rows. </param>
+        /// <summary>
+        /// Creates an instance of <see cref="Models.LogsQueryResult"/> to support <see href="https://aka.ms/azsdk/net/mocking">mocking</see>.
+        /// </summary>
+        /// <param name="allTables"> The list of tables, columns, and rows. </param>
         /// <param name="statistics"> Any object. </param>
         /// <param name="visualization"> Any object. </param>
         /// <param name="error"> Any object. </param>
@@ -84,10 +90,11 @@ public static LogsQueryResult LogsQueryResult(IReadOnlyList<LogsTable> allTables
             return new LogsQueryResult(allTables.ToArray(), statisticsJson, visualizationJson, errorJson);
         }
 
-        /// <summary> Enables the user to create an instance of a <see cref="LogsTableRow"/>. </summary>
+        /// <summary>
+        /// Creates an instance of <see cref="Models.LogsTableRow"/> to support <see href="https://aka.ms/azsdk/net/mocking">mocking</see>.
+        /// </summary>
         /// <param name="columns"> The list of columns. </param>
         /// <param name="values"> An object array representing the rows of the table. </param>
-        /// <returns> A new <see cref="Models.LogsTableRow"/> instance for mocking. </returns>
         public static LogsTableRow LogsTableRow(IEnumerable<LogsTableColumn> columns, IEnumerable<object> values)
         {
             var columnsList = columns.ToArray();
@@ -96,7 +103,9 @@ public static LogsTableRow LogsTableRow(IEnumerable<LogsTableColumn> columns, IE
             return new LogsTableRow(columnMap, columnsList, row);
         }
 
-        /// <summary> Enables the user to create an instance of a <see cref="LogsTable"/>. </summary>
+        /// <summary>
+        /// Creates an instance of <see cref="Models.LogsTable"/> to support <see href="https://aka.ms/azsdk/net/mocking">mocking</see>.
+        /// </summary>
         /// <param name="name"> The name of the table. </param>
         /// <param name="columns"> The list of columns. </param>
         /// <param name="rows"> The list of rows. </param>