From 53315e0bb2bc8c3316704b27a97bbaaa7b3c1b23 Mon Sep 17 00:00:00 2001
From: Youssef Victor <youssefvictor00@gmail.com>
Date: Mon, 16 Dec 2024 10:24:45 +0100
Subject: [PATCH 1/2] Enable CS1591: Missing XML comment for publicly visible
 type or member

---
 Directory.Build.props | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/Directory.Build.props b/Directory.Build.props
index 25e725ef65..2bd5603288 100644
--- a/Directory.Build.props
+++ b/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. -->

From 1f1c485350cbaa2d3a7efa85e47b546fda518c47 Mon Sep 17 00:00:00 2001
From: Youssef1313 <youssefvictor00@gmail.com>
Date: Wed, 18 Dec 2024 09:41:22 +0100
Subject: [PATCH 2/2] Doc progress

---
 .../Builder/TestApplication.cs                |  1 +
 .../IGracefulStopTestExecutionCapability.cs   | 11 ++++
 .../Logging/LogLevel.cs                       |  3 ++
 .../Logging/LoggingExtensions.cs              | 51 +++++++++++++++++++
 .../ErrorMessageOutputDeviceData.cs           | 11 ++++
 .../OutputDevice/ExceptionOutputDeviceData.cs | 11 ++++
 .../WarningMessageOutputDeviceData.cs         | 11 ++++
 7 files changed, 99 insertions(+)

diff --git a/src/Platform/Microsoft.Testing.Platform/Builder/TestApplication.cs b/src/Platform/Microsoft.Testing.Platform/Builder/TestApplication.cs
index 7b618018a9..3691d6a931 100644
--- a/src/Platform/Microsoft.Testing.Platform/Builder/TestApplication.cs
+++ b/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()
diff --git a/src/Platform/Microsoft.Testing.Platform/Capabilities/TestFramework/IGracefulStopTestExecutionCapability.cs b/src/Platform/Microsoft.Testing.Platform/Capabilities/TestFramework/IGracefulStopTestExecutionCapability.cs
index ee8a92dee3..0015c11683 100644
--- a/src/Platform/Microsoft.Testing.Platform/Capabilities/TestFramework/IGracefulStopTestExecutionCapability.cs
+++ b/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);
 }
diff --git a/src/Platform/Microsoft.Testing.Platform/Logging/LogLevel.cs b/src/Platform/Microsoft.Testing.Platform/Logging/LogLevel.cs
index f3500528e9..4a0f96ee0c 100644
--- a/src/Platform/Microsoft.Testing.Platform/Logging/LogLevel.cs
+++ b/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>
diff --git a/src/Platform/Microsoft.Testing.Platform/Logging/LoggingExtensions.cs b/src/Platform/Microsoft.Testing.Platform/Logging/LoggingExtensions.cs
index 3a24bf4469..8a0b09687e 100644
--- a/src/Platform/Microsoft.Testing.Platform/Logging/LoggingExtensions.cs
+++ b/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);
 }
diff --git a/src/Platform/Microsoft.Testing.Platform/OutputDevice/ErrorMessageOutputDeviceData.cs b/src/Platform/Microsoft.Testing.Platform/OutputDevice/ErrorMessageOutputDeviceData.cs
index e7b5cc0cb3..e36ab97388 100644
--- a/src/Platform/Microsoft.Testing.Platform/OutputDevice/ErrorMessageOutputDeviceData.cs
+++ b/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;
 }
diff --git a/src/Platform/Microsoft.Testing.Platform/OutputDevice/ExceptionOutputDeviceData.cs b/src/Platform/Microsoft.Testing.Platform/OutputDevice/ExceptionOutputDeviceData.cs
index e56f33950c..c5a5a499e0 100644
--- a/src/Platform/Microsoft.Testing.Platform/OutputDevice/ExceptionOutputDeviceData.cs
+++ b/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;
 }
diff --git a/src/Platform/Microsoft.Testing.Platform/OutputDevice/WarningMessageOutputDeviceData.cs b/src/Platform/Microsoft.Testing.Platform/OutputDevice/WarningMessageOutputDeviceData.cs
index f4b9ee22cb..bc5962dfc5 100644
--- a/src/Platform/Microsoft.Testing.Platform/OutputDevice/WarningMessageOutputDeviceData.cs
+++ b/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;
 }