Ensure all public APIs are documented (#4920)

.editorconfig

@@ -252,12 +252,6 @@ dotnet_diagnostic.SA1615.severity = none                # SA1615: Element return
 dotnet_diagnostic.SA1633.severity = none                # SA1633: File should have header
 dotnet_diagnostic.SA1649.severity = none                # SA1649: File name should match first type name
 
-# -----------------------------------------------------------------------------------------
-# Globally disabled but enabled for src folder
-dotnet_diagnostic.SA1600.severity = none                # SA1600: Elements should be documented
-dotnet_diagnostic.SA1601.severity = none                # SA1601: Partial elements should be documented
-# -----------------------------------------------------------------------------------------
-
 dotnet_diagnostic.VSTHRD002.severity = none             # VSTHRD002 Avoid problematic synchronous waits
 dotnet_diagnostic.VSTHRD003.severity = none             # VSTHRD003: Avoid awaiting foreign Tasks
 dotnet_diagnostic.VSTHRD105.severity = none             # VSTHRD105: Avoid method overloads that assume TaskScheduler.Current

TestFx.sln

@@ -56,6 +56,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "eng", "eng", "{FE0DF239-0D8
 		eng\Build.props = eng\Build.props
 		eng\coverage.config = eng\coverage.config
 		eng\install-windows-sdk.ps1 = eng\install-windows-sdk.ps1
+		eng\stylecop.json = eng\stylecop.json
 		eng\verify-nupkgs.ps1 = eng\verify-nupkgs.ps1
 		eng\Version.Details.xml = eng\Version.Details.xml
 		eng\Versions.props = eng\Versions.props

eng/Analyzers.props

@@ -12,6 +12,7 @@
     <PackageReference Include="Microsoft.CodeAnalysis.BannedApiAnalyzers" PrivateAssets="all" />
 
     <PackageReference Include="StyleCop.Analyzers" PrivateAssets="all" />
+    <AdditionalFiles Include="$(RepositoryEngineeringDir)stylecop.json" Link="stylecop.json" />
 
     <PackageReference Include="Microsoft.VisualStudio.Threading.Analyzers" PrivateAssets="all" />
   </ItemGroup>

eng/stylecop.json

@@ -0,0 +1,8 @@
+{
+  "settings": {
+    "documentationRules": {
+      "documentInternalElements": false,
+      "documentInterfaces": false
+    }
+  }
+}

samples/FxExtensibility/AssertEx.cs

@@ -5,6 +5,9 @@
 
 namespace MSTest.Extensibility.Samples;
 
+/// <summary>
+/// Extensions for the <see cref="Microsoft.VisualStudio.TestTools.UnitTesting.Assert"/> class.
+/// </summary>
 [SuppressMessage("Naming", "CA1711:Identifiers should not have incorrect suffix", Justification = "This is only some sample type")]
 public static class AssertEx
 {

src/.editorconfig

@@ -11,13 +11,3 @@ root = false
 # CA1822: Mark members as static
 # Bump severity only for source as there are FPs for tests, see https://github.com/microsoft/testfx/issues/1225
 dotnet_diagnostic.CA1822.severity = warning
-
-## Styling conventions
-
-# TODO: Enable this
-# SA1600: Elements should be documented
-dotnet_diagnostic.SA1600.severity = none
-
-# TODO: Enable this
-# SA1601: Partial elements should be documented
-dotnet_diagnostic.SA1601.severity = none

src/Adapter/MSTest.TestAdapter/Execution/LogMessageListener.cs

@@ -103,14 +103,27 @@ public LogMessageListener(bool captureDebugTraces)
     [SuppressMessage("Performance", "CA1822:Mark members as static", Justification = "Part of the public API")]
     public string? DebugTrace => s_redirectedDebugTrace?.ToString();
 
+    /// <summary>
+    /// Gets and clears the standard output.
+    /// </summary>
+    /// <returns>The standard output text.</returns>
     public string? GetAndClearStandardOutput() => _redirectedStandardOutput.ToStringAndClear();
 
+    /// <summary>
+    /// Gets and clears the standard error.
+    /// </summary>
+    /// <returns>The standard error text.</returns>
     public string? GetAndClearStandardError() => _redirectedStandardError.ToStringAndClear();
 
+    /// <summary>
+    /// Gets and clears the debug trace.
+    /// </summary>
+    /// <returns>The debug and trace text.</returns>
     [SuppressMessage("Performance", "CA1822:Mark members as static", Justification = "Part of the public API")]
     public string? GetAndClearDebugTrace()
         => s_redirectedDebugTrace?.ToStringAndClear();
 
+    /// <inheritdoc />
     public void Dispose()
     {
         if (_isDisposed)

src/Adapter/MSTest.TestAdapter/Execution/TestExecutionManager.cs

@@ -46,6 +46,9 @@ public void SendMessage(TestMessageLevel testMessageLevel, string message)
     /// </summary>
     private TestRunCancellationToken? _testRunCancellationToken;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="TestExecutionManager"/> class.
+    /// </summary>
     public TestExecutionManager()
         : this(new EnvironmentWrapper())
     {
@@ -166,6 +169,13 @@ internal async Task RunTestsAsync(IEnumerable<TestCase> tests, IRunContext? runC
         }
     }
 
+    /// <summary>
+    /// Runs the tests.
+    /// </summary>
+    /// <param name="sources">Tests to be run.</param>
+    /// <param name="runContext">Context to use when executing the tests.</param>
+    /// <param name="frameworkHandle">Handle to the framework to record results and to do framework operations.</param>
+    /// <param name="cancellationToken">Test run cancellation token.</param>
 #if DEBUG
     [Obsolete("Use RunTestsAsync instead.")]
 #endif

src/Adapter/MSTest.TestAdapter/Execution/TestMethodInfo.cs

@@ -64,16 +64,34 @@ internal TestMethodInfo(
     /// </summary>
     public bool IsRunnable => StringEx.IsNullOrEmpty(NotRunnableReason);
 
+    /// <summary>
+    /// Gets the parameter types of the test method.
+    /// </summary>
     public ParameterInfo[] ParameterTypes => TestMethod.GetParameters();
 
+    /// <summary>
+    /// Gets the return type of the test method.
+    /// </summary>
     public Type ReturnType => TestMethod.ReturnType;
 
+    /// <summary>
+    /// Gets the name of the class declaring the test method.
+    /// </summary>
     public string TestClassName => Parent.ClassType.FullName!;
 
+    /// <summary>
+    /// Gets the name of the test method.
+    /// </summary>
     public string TestMethodName => TestMethod.Name;
 
+    /// <summary>
+    /// Gets the methodInfo for test method.
+    /// </summary>
     public MethodInfo MethodInfo => TestMethod;
 
+    /// <summary>
+    /// Gets the arguments with which test method is invoked.
+    /// </summary>
     public object?[]? Arguments { get; private set; }
 
     /// <summary>
@@ -95,8 +113,20 @@ internal TestMethodInfo(
 
     internal RetryBaseAttribute? RetryAttribute { get; }
 
-    public Attribute[]? GetAllAttributes(bool inherit) => ReflectHelper.Instance.GetDerivedAttributes<Attribute>(TestMethod, inherit).ToArray();
+    /// <summary>
+    /// Gets all attributes of the test method.
+    /// </summary>
+    /// <param name="inherit">Whether or not getting the attributes that are inherited.</param>
+    /// <returns>An array of the attributes.</returns>
+    public Attribute[]? GetAllAttributes(bool inherit)
+        => ReflectHelper.Instance.GetDerivedAttributes<Attribute>(TestMethod, inherit).ToArray();
 
+    /// <summary>
+    /// Gets all attributes of the test method.
+    /// </summary>
+    /// <typeparam name="TAttributeType">The type of the attributes.</typeparam>
+    /// <param name="inherit">Whether or not getting the attributes that are inherited.</param>
+    /// <returns>An array of the attributes.</returns>
     public TAttributeType[] GetAttributes<TAttributeType>(bool inherit)
         where TAttributeType : Attribute
         => ReflectHelper.Instance.GetDerivedAttributes<TAttributeType>(TestMethod, inherit).ToArray();

src/Adapter/MSTest.TestAdapter/Execution/TestRunCancellationToken.cs

@@ -21,10 +21,6 @@ public class TestRunCancellationToken
     /// </summary>
     private readonly ConcurrentBag<(Action<object?>, object?)> _registeredCallbacks = new();
 
-    public TestRunCancellationToken()
-    {
-    }
-
     /// <summary>
     /// Gets a value indicating whether the test run is canceled.
     /// </summary>

src/Adapter/MSTest.TestAdapter/Extensions/TestResultExtensions.cs

@@ -15,6 +15,9 @@
 
 namespace Microsoft.VisualStudio.TestPlatform.MSTest.TestAdapter.Extensions;
 
+/// <summary>
+/// Extension methods for TestResult.
+/// </summary>
 #if NET6_0_OR_GREATER
 [Obsolete(Constants.PublicTypeObsoleteMessage, DiagnosticId = "MSTESTOBS")]
 #else

src/Adapter/MSTest.TestAdapter/Extensions/UnitTestOutcomeExtensions.cs

@@ -7,6 +7,9 @@
 
 namespace Microsoft.VisualStudio.TestPlatform.MSTest.TestAdapter.Extensions;
 
+/// <summary>
+/// Extension methods for <see cref="UTF.UnitTestOutcome"/>.
+/// </summary>
 #if RELEASE
 #if NET6_0_OR_GREATER
 [Obsolete(Constants.PublicTypeObsoleteMessage, DiagnosticId = "MSTESTOBS")]

src/Adapter/MSTest.TestAdapter/Helpers/IEnvironment.cs

@@ -3,7 +3,13 @@
 
 namespace Microsoft.VisualStudio.TestPlatform.MSTest.TestAdapter.Helpers;
 
+/// <summary>
+/// Interface to abstract environment related information.
+/// </summary>
 internal interface IEnvironment
 {
+    /// <summary>
+    /// Gets the machine name.
+    /// </summary>
     string MachineName { get; }
 }

src/Adapter/MSTest.TestAdapter/ObjectModel/TestMethod.cs

@@ -32,6 +32,13 @@ public sealed class TestMethod : ITestMethod
 
     private readonly ReadOnlyCollection<string?> _hierarchy;
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="TestMethod"/> class.
+    /// </summary>
+    /// <param name="name">The name of the method.</param>
+    /// <param name="fullClassName">The full name of the class declaring the method.</param>
+    /// <param name="assemblyName">The full assembly name.</param>
+    /// <param name="isAsync">Whether the method is async.</param>
 #pragma warning disable IDE0060 // Remove unused parameter - Public API :/
     public TestMethod(string name, string fullClassName, string assemblyName, bool isAsync)
 #pragma warning restore IDE0060 // Remove unused parameter

src/Adapter/MSTest.TestAdapter/ObjectModel/UnitTestResult.cs

@@ -5,6 +5,9 @@
 
 namespace Microsoft.VisualStudio.TestPlatform.MSTest.TestAdapter.ObjectModel;
 
+/// <summary>
+/// Represents the result of a unit test.
+/// </summary>
 [Serializable]
 [DebuggerDisplay("{DisplayName} ({Outcome})")]
 #if RELEASE

src/Adapter/MSTest.TestAdapter/RunConfigurationSettings.cs

@@ -12,6 +12,9 @@
 
 namespace Microsoft.VisualStudio.TestPlatform.MSTest.TestAdapter;
 
+/// <summary>
+/// The run configuration settings.
+/// </summary>
 #if RELEASE
 #if NET6_0_OR_GREATER
 [Obsolete(Constants.PublicTypeObsoleteMessage, DiagnosticId = "MSTESTOBS")]

src/Adapter/MSTest.TestAdapter/TestingPlatformAdapter/TestingPlatformBuilderHook.cs

@@ -6,9 +6,17 @@
 
 namespace Microsoft.VisualStudio.TestTools.UnitTesting;
 
+/// <summary>
+/// This class is used by Microsoft.Testing.Platform.MSBuild to hook into the Testing Platform Builder to add MSTest support.
+/// </summary>
 [SuppressMessage("ApiDesign", "RS0030:Do not use banned APIs", Justification = "We can use MTP from this folder")]
 public static class TestingPlatformBuilderHook
 {
+    /// <summary>
+    /// Adds MSTest support to the Testing Platform Builder.
+    /// </summary>
+    /// <param name="testApplicationBuilder">The test application builder on which registering MSTest.</param>
+    /// <param name="arguments">The test application cli arguments.</param>
 #pragma warning disable IDE0060 // Remove unused parameter
     public static void AddExtensions(ITestApplicationBuilder testApplicationBuilder, string[] arguments)
         => testApplicationBuilder.AddMSTest(() => [Assembly.GetEntryAssembly()!]);

src/Adapter/MSTest.TestAdapter/VSTestAdapter/MSTestExecutor.cs

@@ -49,12 +49,24 @@ internal MSTestExecutor(CancellationToken cancellationToken)
     /// </summary>
     public TestExecutionManager TestExecutionManager { get; protected set; }
 
+    /// <summary>
+    /// Runs the tests.
+    /// </summary>
+    /// <param name="tests">The collection of test cases to run.</param>
+    /// <param name="runContext">The run context.</param>
+    /// <param name="frameworkHandle">The handle to the framework.</param>
 #if DEBUG
     [Obsolete("Use RunTestsAsync instead.")]
 #endif
     public void RunTests(IEnumerable<TestCase>? tests, IRunContext? runContext, IFrameworkHandle? frameworkHandle)
         => RunTestsAsync(tests, runContext, frameworkHandle, null).GetAwaiter().GetResult();
 
+    /// <summary>
+    /// Runs the tests.
+    /// </summary>
+    /// <param name="sources">The collection of assemblies to run.</param>
+    /// <param name="runContext">The run context.</param>
+    /// <param name="frameworkHandle">The handle to the framework.</param>
 #if DEBUG
     [Obsolete("Use RunTestsAsync instead.")]
 #endif
@@ -89,6 +101,9 @@ internal async Task RunTestsAsync(IEnumerable<string>? sources, IRunContext? run
         await RunTestsFromRightContextAsync(frameworkHandle, async testRunToken => await TestExecutionManager.RunTestsAsync(sources, runContext, frameworkHandle, testRunToken));
     }
 
+    /// <summary>
+    /// Cancel the test run.
+    /// </summary>
     public void Cancel()
         => _testRunCancellationToken?.Cancel();
 

src/Adapter/MSTestAdapter.PlatformServices/AssemblyResolver.cs

@@ -284,13 +284,23 @@ private static
 #endif
     string[] GetDirectories(string path) => Directory.GetDirectories(path);
 
+    /// <summary>
+    /// Verifies if a file exists.
+    /// </summary>
+    /// <param name="filePath">The file path.</param>
+    /// <returns><c>true</c> if the file exists; <c>false</c> otherwise.</returns>
 #if NETFRAMEWORK
     protected virtual
 #else
     private static
 #endif
     bool DoesFileExist(string filePath) => File.Exists(filePath);
 
+    /// <summary>
+    /// Loads an assembly from the given path.
+    /// </summary>
+    /// <param name="path">The path of the assembly.</param>
+    /// <returns>The loaded <see cref="Assembly"/>.</returns>
 #if NETFRAMEWORK
     protected virtual
 #else
@@ -303,13 +313,18 @@ private static
 #pragma warning restore IL2026 // Members attributed with RequiresUnreferencedCode may break when trimming
 
 #if NETFRAMEWORK
+    /// <summary>
+    /// Loads an assembly from the given path in a reflection-only context.
+    /// </summary>
+    /// <param name="path">The path of the assembly.</param>
+    /// <returns>The loaded <see cref="Assembly"/>.</returns>
     protected virtual Assembly ReflectionOnlyLoadAssemblyFrom(string path) => Assembly.ReflectionOnlyLoadFrom(path);
 #endif
 
     /// <summary>
     /// It will search for a particular assembly in the given list of directory.
     /// </summary>
-    /// <param name="searchDirectorypaths"> The search Directorypaths. </param>
+    /// <param name="searchDirectorypaths"> The search directory paths. </param>
     /// <param name="name"> The name. </param>
     /// <param name="isReflectionOnly"> Indicates whether this is called under a Reflection Only Load context. </param>
     /// <returns> The <see cref="Assembly"/>. </returns>

src/Adapter/MSTestAdapter.PlatformServices/Deployment/TestRunDirectories.cs

@@ -35,6 +35,10 @@ public class TestRunDirectories
     /// </summary>
     internal const string DeploymentOutDirectorySuffix = "Out";
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="TestRunDirectories"/> class.
+    /// </summary>
+    /// <param name="rootDirectory">The root directory path.</param>
     public TestRunDirectories(string rootDirectory)
     {
         DebugEx.Assert(!StringEx.IsNullOrEmpty(rootDirectory), "rootDirectory");

src/Adapter/MSTestAdapter.PlatformServices/Services/MSTestAdapterSettings.cs

@@ -10,6 +10,9 @@
 
 namespace Microsoft.VisualStudio.TestPlatform.MSTestAdapter.PlatformServices;
 
+/// <summary>
+/// The MSTest settings.
+/// </summary>
 #if RELEASE
 #if NET6_0_OR_GREATER
 [Obsolete(Constants.PublicTypeObsoleteMessage, DiagnosticId = "MSTESTOBS")]
@@ -171,6 +174,11 @@ internal static MSTestAdapterSettings ToSettings(IConfiguration configuration)
         return settings;
     }
 
+    /// <summary>
+    /// Determines if the AppDomain are disabled based of the runsettings.
+    /// </summary>
+    /// <param name="settingsXml">The XML runsettings content.</param>
+    /// <returns><c>true</c> if AppDomains are disabled; <c>false</c> otherwise.</returns>
     public static bool IsAppDomainCreationDisabled(string? settingsXml)
     {
         // Expected format of the json is: -

src/Adapter/MSTestAdapter.PlatformServices/Services/SettingsProvider.cs

@@ -57,6 +57,11 @@ public void Load(XmlReader reader)
 #endif
     }
 
+    /// <summary>
+    /// Gets the properties specific to the source.
+    /// </summary>
+    /// <param name="source">The source.</param>
+    /// <returns>A collection of properties.</returns>
     public IDictionary<string, object> GetProperties(string source)
 #if !WINDOWS_UWP
         => TestDeployment.GetDeploymentInformation(source);