Enable CS1591: Missing XML comment for publicly visible type or member

Directory.Build.props

@@ -1,4 +1,9 @@
 <Project>
+  <PropertyGroup>
+    <!-- This needs to happen before importing Arcade props. -->
+    <!-- Otherwise, Arcade would have already included 1591 in NoWarn -->
+    <SkipArcadeNoWarnCS1591>true</SkipArcadeNoWarnCS1591>
+  </PropertyGroup>
 
   <Import Project="Sdk.props" Sdk="Microsoft.DotNet.Arcade.Sdk" />
   <Import Project="$(RepositoryEngineeringDir)Analyzers.props" />
@@ -18,9 +23,8 @@
         not report warnings for missing comments.
 
         CS1573: Parameter 'parameter' has no matching param tag in the XML comment for 'parameter' (but other parameters do)
-        CS1591: Missing XML comment for publicly visible type or member 'Type_or_Member'
       -->
-    <NoWarn>$(NoWarn),1573,1591</NoWarn>
+    <NoWarn>$(NoWarn),1573</NoWarn>
   </PropertyGroup>
 
   <!-- The TFMs to build and test against. -->

src/Platform/Microsoft.Testing.Platform/Builder/TestApplication.cs

@@ -233,6 +233,7 @@ public void Dispose()
         => (_testHost as IDisposable)?.Dispose();
 
 #if NETCOREAPP
+    /// <inheritdoc />
     public ValueTask DisposeAsync()
         => _testHost is IAsyncDisposable asyncDisposable
             ? asyncDisposable.DisposeAsync()

src/Platform/Microsoft.Testing.Platform/Capabilities/TestFramework/IGracefulStopTestExecutionCapability.cs

@@ -15,5 +15,16 @@ namespace Microsoft.Testing.Platform.Capabilities.TestFramework;
 [Experimental("TPEXP", UrlFormat = "https://aka.ms/testingplatform/diagnostics#{0}")]
 public interface IGracefulStopTestExecutionCapability : ITestFrameworkCapability
 {
+    /// <summary>
+    /// This requests the test framework to stop test execution gracefully.
+    /// </summary>
+    /// <param name="cancellationToken">
+    /// If stopping gracefully is taking long, the user may press Ctrl+C to request
+    /// a hard abort. In that case, test frameworks should respect the cancellation token and finish execution as soon as possible.
+    /// </param>
+    /// <remarks>
+    /// Stopping gracefully is currently used for the --maximum-failed-tests feature.
+    /// Test frameworks may decide that a graceful stop should run any remaining class/assembly cleanups, if needed.
+    /// </remarks>
     Task StopTestExecutionAsync(CancellationToken cancellationToken);
 }

src/Platform/Microsoft.Testing.Platform/Logging/LogLevel.cs

@@ -3,6 +3,9 @@
 
 namespace Microsoft.Testing.Platform.Logging;
 
+/// <summary>
+/// Specifies a logging level used with <see cref="ILogger" /> APIs.
+/// </summary>
 public enum LogLevel
 {
     /// <summary>

src/Platform/Microsoft.Testing.Platform/Logging/LoggingExtensions.cs

@@ -3,6 +3,9 @@
 
 namespace Microsoft.Testing.Platform.Logging;
 
+/// <summary>
+/// A set of extension methods for <see cref="ILogger"/>.
+/// </summary>
 public static class LoggingExtensions
 {
     internal static readonly Func<string, Exception?, string> Formatter =
@@ -13,51 +16,99 @@ exception is not null
 #pragma warning restore RS0030 // Do not use banned APIs
                 : state;
 
+    /// <summary>
+    /// Asynchronously logs a message with <see cref="LogLevel.Trace"/>.
+    /// </summary>
     public static Task LogTraceAsync(this ILogger logger, string message)
         => logger.LogAsync(LogLevel.Trace, message, null, Formatter);
 
+    /// <summary>
+    /// Asynchronously logs a message with <see cref="LogLevel.Debug"/>.
+    /// </summary>
     public static Task LogDebugAsync(this ILogger logger, string message)
         => logger.LogAsync(LogLevel.Debug, message, null, Formatter);
 
+    /// <summary>
+    /// Asynchronously logs a message with <see cref="LogLevel.Information"/>.
+    /// </summary>
     public static Task LogInformationAsync(this ILogger logger, string message)
         => logger.LogAsync(LogLevel.Information, message, null, Formatter);
 
+    /// <summary>
+    /// Asynchronously logs a message with <see cref="LogLevel.Warning"/>.
+    /// </summary>
     public static Task LogWarningAsync(this ILogger logger, string message)
         => logger.LogAsync(LogLevel.Warning, message, null, Formatter);
 
+    /// <summary>
+    /// Asynchronously logs a message with <see cref="LogLevel.Error"/>.
+    /// </summary>
     public static Task LogErrorAsync(this ILogger logger, string message)
         => logger.LogAsync(LogLevel.Error, message, null, Formatter);
 
+    /// <summary>
+    /// Asynchronously logs a message with <see cref="LogLevel.Error"/> which is associated with an exception.
+    /// </summary>
     public static Task LogErrorAsync(this ILogger logger, string message, Exception ex)
         => logger.LogAsync(LogLevel.Error, message, ex, Formatter);
 
+    /// <summary>
+    /// Asynchronously logs an exception with <see cref="LogLevel.Error"/>.
+    /// </summary>
     public static Task LogErrorAsync(this ILogger logger, Exception ex)
     => logger.LogAsync(LogLevel.Error, ex.ToString(), null, Formatter);
 
+    /// <summary>
+    /// Asynchronously logs a message with <see cref="LogLevel.Critical"/>.
+    /// </summary>
     public static Task LogCriticalAsync(this ILogger logger, string message)
         => logger.LogAsync(LogLevel.Critical, message, null, Formatter);
 
+    /// <summary>
+    /// Logs a message with <see cref="LogLevel.Trace"/>.
+    /// </summary>
     public static void LogTrace(this ILogger logger, string message)
     => logger.Log(LogLevel.Trace, message, null, Formatter);
 
+    /// <summary>
+    /// Logs a message with <see cref="LogLevel.Debug"/>.
+    /// </summary>
     public static void LogDebug(this ILogger logger, string message)
         => logger.Log(LogLevel.Debug, message, null, Formatter);
 
+    /// <summary>
+    /// Logs a message with <see cref="LogLevel.Information"/>.
+    /// </summary>
     public static void LogInformation(this ILogger logger, string message)
         => logger.Log(LogLevel.Information, message, null, Formatter);
 
+    /// <summary>
+    /// Logs a message with <see cref="LogLevel.Warning"/>.
+    /// </summary>
     public static void LogWarning(this ILogger logger, string message)
         => logger.Log(LogLevel.Warning, message, null, Formatter);
 
+    /// <summary>
+    /// Logs a message with <see cref="LogLevel.Error"/>.
+    /// </summary>
     public static void LogError(this ILogger logger, string message)
         => logger.Log(LogLevel.Error, message, null, Formatter);
 
+    /// <summary>
+    /// Logs a message with <see cref="LogLevel.Error"/> which is associated with an exception.
+    /// </summary>
     public static void LogError(this ILogger logger, string message, Exception ex)
         => logger.Log(LogLevel.Error, message, ex, Formatter);
 
+    /// <summary>
+    /// Logs an exception with <see cref="LogLevel.Error"/>.
+    /// </summary>
     public static void LogError(this ILogger logger, Exception ex)
         => logger.Log(LogLevel.Error, ex.ToString(), null, Formatter);
 
+    /// <summary>
+    /// Logs a message with <see cref="LogLevel.Critical"/>.
+    /// </summary>
     public static void LogCritical(this ILogger logger, string message)
         => logger.Log(LogLevel.Critical, message, null, Formatter);
 }

src/Platform/Microsoft.Testing.Platform/OutputDevice/ErrorMessageOutputDeviceData.cs

@@ -3,7 +3,18 @@
 
 namespace Microsoft.Testing.Platform.OutputDevice;
 
+/// <summary>
+/// Represents output device data that should be displayed as error.
+/// </summary>
+/// <remarks>
+/// It's up to the output device to decide how to display error messages.
+/// The built-in terminal output device will print errors in red foreground.
+/// The built-in server mode output device will send the data to Test Explorer with Error severity.
+/// </remarks>
 public sealed class ErrorMessageOutputDeviceData(string message) : IOutputDeviceData
 {
+    /// <summary>
+    /// Gets the message text represented by this instance.
+    /// </summary>
     public string Message { get; } = message;
 }

src/Platform/Microsoft.Testing.Platform/OutputDevice/ExceptionOutputDeviceData.cs

@@ -3,7 +3,18 @@
 
 namespace Microsoft.Testing.Platform.OutputDevice;
 
+/// <summary>
+/// Represents output device data that is associated with an exception.
+/// </summary>
+/// <remarks>
+/// It's up to the output device to decide how to display exceptions.
+/// The built-in terminal output device will print the exception in red foreground.
+/// The built-in server mode output device will send the data to Test Explorer with Error severity.
+/// </remarks>
 public sealed class ExceptionOutputDeviceData(Exception exception) : IOutputDeviceData
 {
+    /// <summary>
+    /// Gets the exception associated with this instance.
+    /// </summary>
     public Exception Exception { get; } = exception;
 }

src/Platform/Microsoft.Testing.Platform/OutputDevice/WarningMessageOutputDeviceData.cs

@@ -3,7 +3,18 @@
 
 namespace Microsoft.Testing.Platform.OutputDevice;
 
+/// <summary>
+/// Represents output device data that should be displayed as warning.
+/// </summary>
+/// <remarks>
+/// It's up to the output device to decide how to display error messages.
+/// The built-in terminal output device will print warnings in yellow foreground.
+/// The built-in server mode output device will send the data to Test Explorer with Warning severity.
+/// </remarks>
 public sealed class WarningMessageOutputDeviceData(string message) : IOutputDeviceData
 {
+    /// <summary>
+    /// Gets the message text represented by this instance.
+    /// </summary>
     public string Message { get; } = message;
 }