Add XML documentation comments to public APIs #314

Added XML doc comments to public classes, methods, and properties throughout the codebase to improve API discoverability and enable NuGet documentation generation. Updated the project file to generate XML documentation output and suppress missing comment warnings. No functional changes were made.

Author: Arash-Sabet

src/Abstracts/TestBed.cs

@@ -1,43 +1,59 @@
 namespace Xunit.Microsoft.DependencyInjection.Abstracts;
 
+/// <summary>
+/// Base class for test classes which use a fixture of type <typeparamref name="TFixture"/>.
+/// Provides synchronous and asynchronous disposal semantics and a hook (<see cref="Clear"/>)
+/// that derived classes can override to release managed resources created during tests.
+/// </summary>
+/// <typeparam name="TFixture">The fixture type shared across all tests in the class.</typeparam>
 public class TestBed<TFixture>(ITestOutputHelper testOutputHelper, TFixture fixture) : IDisposable, IClassFixture<TFixture>, IAsyncDisposable
 	where TFixture : class
 {
+	/// <summary>
+	/// The <see cref="ITestOutputHelper"/> used to write diagnostic output during test execution.
+	/// </summary>
 	protected readonly ITestOutputHelper _testOutputHelper = testOutputHelper;
+
+	/// <summary>
+	/// The fixture instance supplied by xUnit for this test class.
+	/// </summary>
 	protected readonly TFixture _fixture = fixture;
+
 	private bool _disposedValue;
 	private bool _disposedAsync;
 
+	/// <summary>
+	/// Releases managed resources. Override to add custom cleanup logic. Unmanaged resources
+	/// should be released only if added by derived classes.
+	/// </summary>
+	/// <param name="disposing">True when called from <see cref="Dispose()"/>; false when from a finalizer.</param>
 	protected virtual void Dispose(bool disposing)
 	{
 		if (!_disposedValue)
 		{
 			if (disposing)
 			{
-				// TODO: dispose managed state (managed objects)
+				// Dispose managed state
 				Clear();
 			}
-
-			// TODO: free unmanaged resources (unmanaged objects) and override finalizer
-			// TODO: set large fields to null
 			_disposedValue = true;
 		}
 	}
 
-	// // TODO: override finalizer only if 'Dispose(bool disposing)' has code to free unmanaged resources
-	// ~AbstractTest()
-	// {
-	//     // Do not change this code. Put cleanup code in 'Dispose(bool disposing)' method
-	//     Dispose(disposing: false);
-	// }
+	// Finalizer intentionally omitted. Add only if unmanaged resources are introduced.
 
+	/// <summary>
+	/// Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
+	/// </summary>
 	public void Dispose()
 	{
-		// Do not change this code. Put cleanup code in 'Dispose(bool disposing)' method
 		Dispose(disposing: true);
 		GC.SuppressFinalize(this);
 	}
 
+	/// <summary>
+	/// Asynchronously disposes resources. Calls <see cref="DisposeAsyncCore"/> once.
+	/// </summary>
 	public async ValueTask DisposeAsync()
 	{
 		if (!_disposedAsync)
@@ -48,6 +64,14 @@ public async ValueTask DisposeAsync()
 		}
 	}
 
+	/// <summary>
+	/// Override to clear managed resources created by a derived test class.
+	/// </summary>
 	protected virtual void Clear() { }
+
+	/// <summary>
+	/// Override to implement asynchronous disposal of resources.
+	/// Default implementation is a completed <see cref="ValueTask"/>.
+	/// </summary>
 	protected virtual ValueTask DisposeAsyncCore() => new();
 }

src/Abstracts/TestBedFactoryFixture.cs

@@ -36,9 +36,18 @@ public object CreateTestInstance(Type testType, ITestOutputHelper testOutputHelp
 
 
 
+	/// <summary>
+	/// Creates an instance of <typeparamref name="T"/> using the best matching constructor.
+	/// </summary>
 	private T CreateInstance<T>(IServiceProvider serviceProvider, ITestOutputHelper testOutputHelper, params object[] additionalParameters)
 		where T : class => (T)CreateInstance(typeof(T), serviceProvider, testOutputHelper, additionalParameters);
 
+	/// <summary>
+	/// Core implementation for creating the test instance by iterating available constructors
+	/// (public &amp; non-public) and resolving parameters from provided instances, test output helper,
+	/// the fixture itself or the service provider (including keyed services when annotated).
+	/// </summary>
+	/// <exception cref="InvalidOperationException">Thrown when no suitable constructor can be satisfied.</exception>
 	private object CreateInstance(Type testType, IServiceProvider serviceProvider, ITestOutputHelper testOutputHelper, params object[] additionalParameters)
 	{
 		// Find the best constructor (including internal constructors)

src/Abstracts/TestBedFixture.cs

@@ -2,6 +2,12 @@
 
 namespace Xunit.Microsoft.DependencyInjection.Abstracts;
 
+/// <summary>
+/// Base fixture abstraction that configures dependency injection, configuration sources
+/// (JSON, user secrets, environment variables) and logging for test classes.
+/// Derived fixtures register services via <see cref="AddServices"/> and configuration files
+/// via <see cref="GetTestAppSettings"/>.
+/// </summary>
 public abstract class TestBedFixture : IDisposable, IAsyncDisposable
 {
 	private readonly ServiceCollection _services;
@@ -10,6 +16,9 @@ public abstract class TestBedFixture : IDisposable, IAsyncDisposable
 	private bool _disposedAsync;
 	private bool _servicesAdded;
 
+	/// <summary>
+	/// Initializes the fixture, creating a service collection and configuration builder.
+	/// </summary>
 	protected TestBedFixture()
 	{
 		_services = new ServiceCollection();
@@ -19,9 +28,21 @@ protected TestBedFixture()
 		_servicesAdded = false;
 	}
 
+	/// <summary>
+	/// The combined configuration root composed of JSON files, user secrets (optional) and environment variables.
+	/// </summary>
 	public IConfigurationRoot? Configuration { get; private set; }
+
+	/// <summary>
+	/// The configuration builder used to assemble the <see cref="Configuration"/>.
+	/// </summary>
 	public IConfigurationBuilder ConfigurationBuilder { get; private set; }
 
+	/// <summary>
+	/// Builds (lazily) and returns the root <see cref="ServiceProvider"/> including logging provider and options.
+	/// Subsequent calls return a cached provider.
+	/// </summary>
+	/// <param name="testOutputHelper">The test output helper used for logging.</param>
 	public ServiceProvider GetServiceProvider(ITestOutputHelper testOutputHelper)
 	{
 		if (_serviceProvider is not null)
@@ -38,22 +59,37 @@ public ServiceProvider GetServiceProvider(ITestOutputHelper testOutputHelper)
 		return _serviceProvider = _services.BuildServiceProvider();
 	}
 
+	/// <summary>
+	/// Resolves a scoped service of type <typeparamref name="T"/> using a new scope.
+	/// </summary>
 	public T? GetScopedService<T>(ITestOutputHelper testOutputHelper)
 	{
 		var serviceProvider = GetServiceProvider(testOutputHelper);
 		using var scope = serviceProvider.CreateScope();
 		return scope.ServiceProvider.GetService<T>();
 	}
 
+	/// <summary>
+	/// Creates and returns a new asynchronous service scope.
+	/// Caller is responsible for disposing the returned <see cref="AsyncServiceScope"/>.
+	/// </summary>
 	public AsyncServiceScope GetAsyncScope(ITestOutputHelper testOutputHelper)
 	{
 		var serviceProvider = GetServiceProvider(testOutputHelper);
 		return serviceProvider.CreateAsyncScope();
 	}
 
+	/// <summary>
+	/// Resolves a service of type <typeparamref name="T"/> from the root provider.
+	/// </summary>
 	public T? GetService<T>(ITestOutputHelper testOutputHelper)
 		=> GetServiceProvider(testOutputHelper).GetService<T>();
 
+	/// <summary>
+	/// Resolves a keyed service of type <typeparamref name="T"/>.
+	/// </summary>
+	/// <param name="key">The key identifying the registration.</param>
+	/// <param name="testOutputHelper">The test output helper used for logging and provider access.</param>
 	public T? GetKeyedService<T>([DisallowNull] string key, ITestOutputHelper testOutputHelper)
 		=> GetServiceProvider(testOutputHelper).GetKeyedService<T>(key);
 
@@ -64,13 +100,15 @@ public AsyncServiceScope GetAsyncScope(ITestOutputHelper testOutputHelper)
 	//     Dispose(disposing: false);
 	// }
 
+	/// <inheritdoc />
 	public void Dispose()
 	{
 		// Do not change this code. Put cleanup code in 'Dispose(bool disposing)' method
 		Dispose(disposing: true);
 		GC.SuppressFinalize(this);
 	}
 
+	/// <inheritdoc />
 	public async ValueTask DisposeAsync()
 	{
 		if (!_disposedAsync)
@@ -82,13 +120,31 @@ public async ValueTask DisposeAsync()
 		GC.SuppressFinalize(this);
 	}
 
+	/// <summary>
+	/// Adds services to the service collection. Called once before building the provider.
+	/// </summary>
 	protected abstract void AddServices(IServiceCollection services, IConfiguration? configuration);
+
+	/// <summary>
+	/// Returns the test application settings descriptors (JSON files) to include.
+	/// </summary>
 	protected abstract IEnumerable<TestAppSettings> GetTestAppSettings();
+
+	/// <summary>
+	/// Override to asynchronously clean up resources created by the fixture.
+	/// </summary>
 	protected abstract ValueTask DisposeAsyncCore();
 
+	/// <summary>
+	/// Allows derived fixtures to customize logging by adding or decorating providers.
+	/// </summary>
 	protected virtual ILoggingBuilder AddLoggingProvider(ILoggingBuilder loggingBuilder, ILoggerProvider loggerProvider)
 		=> loggingBuilder.AddProvider(loggerProvider);
 
+	/// <summary>
+	/// Override to add user secrets to the provided configuration builder when needed.
+	/// Default implementation does nothing.
+	/// </summary>
 	protected virtual void AddUserSecrets(IConfigurationBuilder configurationBuilder) { }
 
 	private IConfigurationRoot? GetConfigurationRoot()
@@ -110,6 +166,9 @@ private IConfigurationRoot GetConfigurationRoot(IEnumerable<TestAppSettings> con
 		return ConfigurationBuilder.Build();
 	}
 
+	/// <summary>
+	/// Disposes managed resources created by the fixture including the root service provider.
+	/// </summary>
 	protected virtual void Dispose(bool disposing)
 	{
 		if (!_disposedValue)
@@ -124,8 +183,6 @@ protected virtual void Dispose(bool disposing)
 				_services.Clear();
 			}
 
-			// TODO: free unmanaged resources (unmanaged objects) and override finalizer
-			// TODO: set large fields to null
 			_disposedValue = true;
 		}
 	}

src/Abstracts/TestBedWithDI.cs

@@ -83,13 +83,19 @@ private void InjectProperties(Type derivedType)
 	/// </summary>
 	/// <typeparam name="T">The service type</typeparam>
 	/// <returns>The resolved service instance</returns>
+	/// <summary>
+	/// Convenience helper to resolve a service of type <typeparamref name="T"/>.
+	/// </summary>
 	protected T? GetService<T>() => _fixture.GetService<T>(_testOutputHelper);
 
 	/// <summary>
 	/// Resolves a scoped service of type T from the fixture's service provider
 	/// </summary>
 	/// <typeparam name="T">The service type</typeparam>
 	/// <returns>The resolved service instance</returns>
+	/// <summary>
+	/// Convenience helper to resolve a scoped service of type <typeparamref name="T"/>.
+	/// </summary>
 	protected T? GetScopedService<T>() => _fixture.GetScopedService<T>(_testOutputHelper);
 
 	/// <summary>

src/Attributes/TestOrderAttribute.cs

@@ -1,7 +1,14 @@
 namespace Xunit.Microsoft.DependencyInjection.Attributes;
 
+/// <summary>
+/// Specifies execution ordering for test methods when used with <see cref="TestsOrder.TestPriorityOrderer"/>.
+/// Lower priority values execute first; methods with the same priority are ordered alphabetically.
+/// </summary>
 [AttributeUsage(AttributeTargets.Method, AllowMultiple = false)]
 public class TestOrderAttribute(int priority) : Attribute
 {
+	/// <summary>
+	/// Gets the priority assigned to the test method.
+	/// </summary>
 	public int Priority { get; } = priority;
 }

src/Logging/NilLoggerProvider.cs

@@ -1,10 +1,16 @@
 namespace Xunit.Microsoft.DependencyInjection.Logging;
 
+/// <summary>
+/// Logger provider that discards all log messages (Null Object pattern).
+/// Useful for suppressing output when no <see cref="ITestOutputHelper"/> is available.
+/// </summary>
 public sealed class NilLoggerProvider : ILoggerProvider
 {
+	/// <inheritdoc />
 	public ILogger CreateLogger(string categoryName)
 		=> new NilLogger();
 
+	/// <inheritdoc />
 	public void Dispose()
 	{
 	}

src/Logging/NoOpDisposable.cs

@@ -1,6 +1,10 @@
 namespace Xunit.Microsoft.DependencyInjection.Logging;
 
+/// <summary>
+/// Lightweight disposable that performs no action. Used to satisfy API contracts requiring a disposable scope.
+/// </summary>
 internal class NoOpDisposable : IDisposable
 {
+	/// <inheritdoc />
 	public void Dispose() { }
 }

src/Logging/OutputLogger.cs

@@ -1,10 +1,16 @@
 namespace Xunit.Microsoft.DependencyInjection.Logging;
 
+/// <summary>
+/// An <see cref="ILogger"/> implementation that writes log messages to the xUnit <see cref="ITestOutputHelper"/>.
+/// </summary>
 public class OutputLogger(string categoryName, ITestOutputHelper testOutputHelper) : ILogger
 {
 	private readonly ITestOutputHelper _testOutputHelper = testOutputHelper;
 	private readonly string _categoryName = categoryName;
 
+	/// <summary>
+	/// Creates a logger with the default category name "Tests".
+	/// </summary>
 	public OutputLogger(ITestOutputHelper testOutputHelper)
 		: this("Tests", testOutputHelper)
 	{
@@ -16,6 +22,7 @@ public OutputLogger(ITestOutputHelper testOutputHelper)
 	public bool IsEnabled(LogLevel logLevel)
 		=> true;
 
+	/// <inheritdoc />
 	public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func<TState, Exception, string> formatter)
 	{
 		try

src/Logging/OutputLoggerProvider.cs

@@ -1,5 +1,9 @@
 namespace Xunit.Microsoft.DependencyInjection.Logging;
 
+/// <summary>
+/// Logger provider that creates <see cref="OutputLogger"/> instances writing to a shared
+/// <see cref="ITestOutputHelper"/>.
+/// </summary>
 public class OutputLoggerProvider(ITestOutputHelper testOutputHelper) : ILoggerProvider
 {
 	private readonly ITestOutputHelper _testOutputHelper = testOutputHelper;

src/TestAppSettings.cs

@@ -1,7 +1,17 @@
 namespace Xunit.Microsoft.DependencyInjection;
 
+/// <summary>
+/// Represents a test configuration file to be loaded into the fixture configuration root.
+/// </summary>
 public class TestAppSettings
 {
+	/// <summary>
+	/// The JSON file name (relative or absolute) to load.
+	/// </summary>
 	public string? Filename { get; set; }
+
+	/// <summary>
+	/// Indicates whether the file is optional. When true missing files do not cause an exception.
+	/// </summary>
 	public bool IsOptional { get; set; } = false;
 }