docs: Updated XML Summaries

Author: samtrion

src/NetEvolve.ProjectBuilders.TUnit/TemporaryDirectory.cs

@@ -9,36 +9,55 @@
 
 /// <summary>
 /// Represents a temporary directory that is automatically created and cleaned up for TUnit tests.
-/// This class integrates with TUnit's <see cref="IAsyncInitializer"/> to automatically initialize
-/// the temporary directory before test execution and implements <see cref="IAsyncDisposable"/>
-/// to ensure proper cleanup after test completion.
 /// </summary>
 /// <remarks>
 /// <para>
-/// This class serves as a TUnit-specific wrapper around <see cref="TemporaryDirectoryBuilder"/>
-/// to provide seamless integration with TUnit's test lifecycle management.
+/// This class serves as a TUnit-specific adapter around <see cref="TemporaryDirectoryBuilder"/>
+/// to provide seamless integration with TUnit's test lifecycle management. It implements both
+/// <see cref="IAsyncInitializer"/> for automatic initialization and <see cref="IAsyncDisposable"/>
+/// for automatic cleanup.
 /// </para>
 /// <para>
-/// The temporary directory is created in a unique location to avoid conflicts between parallel
-/// test executions and is automatically deleted when disposed, ensuring clean test isolation.
+/// The temporary directory is automatically:
+/// <list type="bullet">
+/// <item><description>Created before test execution via <see cref="IAsyncInitializer.InitializeAsync"/></description></item>
+/// <item><description>Cleaned up and deleted after test completion via <see cref="DisposeAsync"/></description></item>
+/// <item><description>Placed in a unique location to avoid conflicts between parallel test executions</description></item>
+/// </list>
 /// </para>
 /// <para>
-/// Usage in TUnit tests:
+/// Provides directory and file management methods through <see cref="ITemporaryDirectoryBuilder"/>,
+/// including directory creation, file creation, and path resolution.
+/// </para>
+/// <para>
+/// Usage example in TUnit tests:
 /// <code>
 /// [ClassDataSource&lt;TemporaryDirectory&gt;]
 /// public class MyTests(TemporaryDirectory directory)
 /// {
 ///     [Test]
-///     public async Task MyTest()
+///     public async Task TestCreateFile()
 ///     {
-///         var filePath = directory.GetFilePath("test.txt");
 ///         using var stream = directory.CreateFile("test.txt");
-///         // ... test code ...
+///         stream.WriteAsync(new byte[] { 1, 2, 3 }, 0, 3);
+///
+///         string fullPath = directory.GetFilePath("test.txt");
+///         Assert.That(File.Exists(fullPath));
+///     }
+///
+///     [Test]
+///     public void TestCreateDirectory()
+///     {
+///         var subDir = directory.CreateDirectory("subdirectory");
+///         Assert.That(Directory.Exists(Path.Combine(directory.FullPath, "subdirectory")));
 ///     }
 /// }
 /// </code>
 /// </para>
 /// </remarks>
+/// <seealso cref="IAsyncInitializer"/>
+/// <seealso cref="IAsyncDisposable"/>
+/// <seealso cref="TemporaryDirectoryBuilder"/>
 public sealed class TemporaryDirectory : ITemporaryDirectoryBuilder, IAsyncInitializer
 {
     private readonly TemporaryDirectoryBuilder _directory = new();

src/NetEvolve.ProjectBuilders.XUnit/TemporaryDirectoryFixture.cs

@@ -9,21 +9,30 @@
 
 /// <summary>
 /// Represents a temporary directory fixture that is automatically created and cleaned up for xUnit tests.
-/// This class integrates with xUnit's <see cref="IAsyncLifetime"/> to automatically initialize
-/// the temporary directory before test execution and implements <see cref="IAsyncDisposable"/>
-/// to ensure proper cleanup after test completion.
 /// </summary>
 /// <remarks>
 /// <para>
-/// This class serves as an xUnit-specific wrapper around <see cref="TemporaryDirectoryBuilder"/>
+/// This class serves as an xUnit-specific adapter around <see cref="TemporaryDirectoryBuilder"/>
 /// to provide seamless integration with xUnit's test lifecycle management through the fixture pattern.
+/// It implements <see cref="IAsyncLifetime"/> for automatic initialization and cleanup.
 /// </para>
 /// <para>
-/// The temporary directory is created in a unique location to avoid conflicts between parallel
-/// test executions and is automatically deleted when disposed, ensuring clean test isolation.
+/// The temporary directory is automatically:
+/// <list type="bullet">
+/// <item><description>Created before test execution via <see cref="IAsyncLifetime.InitializeAsync"/></description></item>
+/// <item><description>Cleaned up and deleted after test completion via <see cref="IAsyncLifetime.DisposeAsync"/></description></item>
+/// <item><description>Placed in a unique location to avoid conflicts between parallel test executions</description></item>
+/// </list>
 /// </para>
 /// <para>
-/// Usage in xUnit tests with class fixtures:
+/// Provides directory and file management methods through <see cref="ITemporaryDirectoryBuilder"/>,
+/// including directory creation, file creation, and path resolution.
+/// </para>
+/// <para>
+/// Works with xUnit class fixtures and collection fixtures for flexible test lifecycle management.
+/// </para>
+/// <para>
+/// Class fixture usage example:
 /// <code>
 /// public class MyTests : IClassFixture&lt;TemporaryDirectoryFixture&gt;
 /// {
@@ -35,27 +44,26 @@
 ///     }
 ///
 ///     [Fact]
-///     public void MyTest()
+///     public void TestCreateFile()
 ///     {
-///         // Directory is automatically initialized via IAsyncLifetime
-///         var filePath = _directory.GetFilePath("test.txt");
+///         // Directory is automatically initialized before this test runs
 ///         using var stream = _directory.CreateFile("test.txt");
-///         // ... test code ...
-///
-///         // Directory is automatically cleaned up after all tests in the class complete
+///         var fullPath = _directory.GetFilePath("test.txt");
+///         Assert.True(File.Exists(fullPath));
+///         // Directory is automatically cleaned up after this test completes
 ///     }
 /// }
 /// </code>
 /// </para>
 /// <para>
-/// Usage in xUnit tests with collection fixtures:
+/// Collection fixture usage example:
 /// <code>
-/// [CollectionDefinition("Temporary Directory")]
+/// [CollectionDefinition("Temporary Directory Collection")]
 /// public class TemporaryDirectoryCollection : ICollectionFixture&lt;TemporaryDirectoryFixture&gt;
 /// {
 /// }
 ///
-/// [Collection("Temporary Directory")]
+/// [Collection("Temporary Directory Collection")]
 /// public class MyTests
 /// {
 ///     private readonly TemporaryDirectoryFixture _directory;
@@ -66,18 +74,26 @@
 ///     }
 ///
 ///     [Fact]
-///     public void MyTest()
+///     public void TestOne()
 ///     {
 ///         // Directory is shared across all tests in the collection
-///         var filePath = _directory.GetFilePath("test.txt");
-///         // ... test code ...
+///         using var stream = _directory.CreateFile("test1.txt");
+///     }
+///
+///     [Fact]
+///     public void TestTwo()
+///     {
+///         // Same directory instance from TestOne
+///         using var stream = _directory.CreateFile("test2.txt");
 ///     }
 /// }
 /// </code>
 /// </para>
 /// </remarks>
 /// <seealso cref="IClassFixture{TFixture}"/>
 /// <seealso cref="ICollectionFixture{TFixture}"/>
+/// <seealso cref="IAsyncLifetime"/>
+/// <seealso cref="TemporaryDirectoryBuilder"/>
 public sealed class TemporaryDirectoryFixture : ITemporaryDirectoryBuilder, IAsyncLifetime
 {
     private readonly TemporaryDirectoryBuilder _directory = new();

src/NetEvolve.ProjectBuilders/Abstractions/IFileBuilder.cs

@@ -1,6 +1,20 @@
 namespace NetEvolve.ProjectBuilders.Abstractions;
 
 /// <summary>
-/// Represents an unspecific file builder, which can be configured to build a file.
+/// Represents a generic file builder interface for creating project files.
 /// </summary>
+/// <remarks>
+/// <para>
+/// This interface serves as a base abstraction for all file builders in the project.
+/// It extends <see cref="IObjectBuilder"/> to provide async creation and disposal capabilities
+/// for file-based objects used in the project building process.
+/// </para>
+/// <para>
+/// Implementations of this interface are responsible for creating specific types of files,
+/// such as project files (.csproj, .vbproj) and configuration files (global.json).
+/// </para>
+/// </remarks>
+/// <seealso cref="IObjectBuilder"/>
+/// <seealso cref="IProjectBuilder"/>
+/// <seealso cref="IGlobalJsonBuilder"/>
 public interface IFileBuilder : IObjectBuilder { }

src/NetEvolve.ProjectBuilders/Abstractions/IGlobalJsonBuilder.cs

@@ -3,27 +3,76 @@
 using NetEvolve.ProjectBuilders.Models;
 
 /// <summary>
-/// Represents a global.json file builder.
+/// Represents a builder for creating and configuring global.json SDK configuration files.
 /// </summary>
+/// <remarks>
+/// <para>
+/// This interface provides a fluent API for building global.json files that configure
+/// the .NET SDK version and roll-forward behavior for a project or directory tree.
+/// </para>
+/// <para>
+/// The global.json file is used to:
+/// <list type="bullet">
+/// <item><description>Pin a specific .NET SDK version for the project</description></item>
+/// <item><description>Configure SDK roll-forward policies</description></item>
+/// <item><description>Allow or disallow prerelease SDK versions</description></item>
+/// </list>
+/// </para>
+/// <para>
+/// See <see href="https://learn.microsoft.com/en-us/dotnet/core/tools/global-json"/> for more information.
+/// </para>
+/// </remarks>
+/// <seealso cref="IFileBuilder"/>
 public interface IGlobalJsonBuilder : IFileBuilder
 {
     /// <summary>
-    /// If set to <see langword="true" />, the global.json file will allow prerelease versions.
+    /// Configures whether prerelease SDK versions are allowed for this project.
     /// </summary>
+    /// <remarks>
+    /// When set to <see langword="true"/>, the .NET SDK resolution will consider prerelease
+    /// versions that match the specified major, minor, and patch versions. The default is
+    /// <see langword="false"/>, which restricts to released SDK versions only.
+    /// </remarks>
     /// <param name="allowPrerelease">
-    /// If set to <see langword="true" />, the global.json file will allow prerelease versions.
+    /// <see langword="true"/> to allow prerelease SDK versions; <see langword="false"/> otherwise.
     /// </param>
-    /// <returns>The current instance of the <see cref="IGlobalJsonBuilder"/>.</returns>
+    /// <returns>The current instance of the <see cref="IGlobalJsonBuilder"/> for fluent chaining.</returns>
     IGlobalJsonBuilder SetAllowPrerelease(bool allowPrerelease);
 
     /// <summary>
-    /// Sets the roll forward option for the global.json file.
+    /// Sets the roll-forward behavior for SDK version resolution.
     /// </summary>
+    /// <remarks>
+    /// The roll-forward policy determines how the SDK resolves versions when the exact
+    /// specified version is not available. Different policies allow rolling forward to
+    /// different release levels (patch, feature, minor, or major).
+    /// </remarks>
     /// <param name="rollForward">
-    /// The roll forward option for the global.json file.
+    /// The roll-forward policy to apply. For example, <see cref="RollForward.LatestMinor"/>
+    /// allows rolling forward to the latest patch and feature level within the same major.minor version.
     /// </param>
-    /// <returns>The current instance of the <see cref="IGlobalJsonBuilder"/>.</returns>
+    /// <returns>The current instance of the <see cref="IGlobalJsonBuilder"/> for fluent chaining.</returns>
+    /// <seealso cref="RollForward"/>
     IGlobalJsonBuilder SetRollForward(RollForward rollForward);
 
+    /// <summary>
+    /// Sets the .NET SDK version to use for this project or directory tree.
+    /// </summary>
+    /// <remarks>
+    /// The version string should be in semantic versioning format, for example "8.0.204" or "10.0.100".
+    /// This version becomes the preferred SDK version for all dotnet commands executed in this
+    /// directory and its subdirectories (unless overridden by nested global.json files).
+    /// </remarks>
+    /// <param name="runtimeVersion">
+    /// The SDK version as a string (e.g., "8.0.204", "10.0.100").
+    /// Must not be <see langword="null"/>, empty, or whitespace.
+    /// </param>
+    /// <returns>The current instance of the <see cref="IGlobalJsonBuilder"/> for fluent chaining.</returns>
+    /// <exception cref="ArgumentNullException">
+    /// Thrown when <paramref name="runtimeVersion"/> is <see langword="null"/>.
+    /// </exception>
+    /// <exception cref="ArgumentException">
+    /// Thrown when <paramref name="runtimeVersion"/> is empty or whitespace.
+    /// </exception>
     IGlobalJsonBuilder SetRuntimeSdk(string runtimeVersion);
 }

src/NetEvolve.ProjectBuilders/Abstractions/IItemGroup.cs

@@ -3,23 +3,39 @@
 using System.Collections.ObjectModel;
 
 /// <summary>
-/// Represents a <b>&lt;ItemGroup&gt;</b> in a project file.
+/// Represents an ItemGroup element in an MSBuild project file.
 /// </summary>
+/// <remarks>
+/// <para>
+/// The ItemGroup is one of the fundamental building blocks in MSBuild project files. It contains
+/// items that represent inputs to the build process, such as package references, project references,
+/// framework references, and other file-based items.
+/// </para>
+/// <para>
+/// Each item in the group can have various attributes and properties that influence how the
+/// build system processes it. Items can be conditional using the Condition attribute.
+/// </para>
+/// <para>
+/// See <see href="https://learn.microsoft.com/en-us/visualstudio/msbuild/itemgroup-element-msbuild"/> for more information.
+/// </para>
+/// </remarks>
 public interface IItemGroup
 {
     /// <summary>
-    /// The items of the item group.
+    /// Gets a read-only collection of items in this item group.
     /// </summary>
+    /// <value>A read-only collection of <see cref="IItemGroupItem"/> objects.</value>
     ReadOnlyCollection<IItemGroupItem> Items { get; }
 
     /// <summary>
-    /// Adds a new item to the item group.
+    /// Adds a new item of the specified type to this item group.
     /// </summary>
     /// <typeparam name="T">
-    /// The type of the item to add.
+    /// The type of the item to add. Must be a non-abstract class implementing <see cref="IItemGroupItem"/>
+    /// with a public parameterless constructor.
     /// </typeparam>
     /// <returns>
-    /// The added item.
+    /// The newly created and added item instance.
     /// </returns>
     T Add<T>()
         where T : class, IItemGroupItem, new();