[Xamarin.ProjectTools] document test framework APIs (#10380)

This PR adds comprehensive XML documentation to the core classes and
methods in the `src/Xamarin.Android.Build.Tasks/Tests/Xamarin.ProjectTools/`
directory, addressing the lack of documentation in the test suite
supporting API.

The `Xamarin.ProjectTools` test framework provides essential
infrastructure for testing Xamarin.Android build scenarios, but many
of its public, protected, and internal APIs lacked proper
documentation. This made it difficult for developers to understand how
to use the framework effectively.

Author: Copilot

src/Xamarin.Android.Build.Tasks/Tests/Xamarin.ProjectTools/Android/AndroidBuildActions.cs

@@ -7,28 +7,125 @@
 
 namespace Xamarin.ProjectTools
 {
+	/// <summary>
+	/// Contains constant values for Android-specific MSBuild item types (build actions).
+	/// These constants provide a centralized way to reference Android build actions
+	/// used in Xamarin.Android projects for various Android-specific file types.
+	/// </summary>
+	/// <remarks>
+	/// These build actions are specific to Xamarin.Android and determine how Android
+	/// assets, resources, libraries, and other Android-specific files are processed
+	/// during the build. Used in conjunction with <see cref="BuildActions"/> for
+	/// complete build item type coverage.
+	/// </remarks>
+	/// <seealso cref="BuildActions"/>
+	/// <seealso cref="BuildItem"/>
+	/// <seealso cref="AndroidItem"/>
 	public static class AndroidBuildActions
 	{
+		/// <summary>
+		/// Build action for Android resource files (layout, drawable, values, etc.).
+		/// </summary>
 		public const string AndroidResource = "AndroidResource";
+		
+		/// <summary>
+		/// Build action for Android asset files stored in the assets folder.
+		/// </summary>
 		public const string AndroidAsset = "AndroidAsset";
+		
+		/// <summary>
+		/// Build action for Android AAR library files.
+		/// </summary>
 		public const string AndroidAarLibrary = "AndroidAarLibrary";
+		
+		/// <summary>
+		/// Build action for Android environment variable files.
+		/// </summary>
 		public const string AndroidEnvironment = "AndroidEnvironment";
+		
+		/// <summary>
+		/// Build action for Android interface description language files.
+		/// </summary>
 		public const string AndroidInterfaceDescription = "AndroidInterfaceDescription";
+		
+		/// <summary>
+		/// Build action for Java source files to be compiled as part of the Android project.
+		/// </summary>
 		public const string AndroidJavaSource = "AndroidJavaSource";
+		
+		/// <summary>
+		/// Build action for Java library JAR files.
+		/// </summary>
 		public const string AndroidJavaLibrary = "AndroidJavaLibrary";
+		
+		/// <summary>
+		/// Build action for Android library project references.
+		/// </summary>
 		public const string AndroidLibrary = "AndroidLibrary";
+		
+		/// <summary>
+		/// Build action for Maven-based Android library dependencies.
+		/// </summary>
 		public const string AndroidMavenLibrary = "AndroidMavenLibrary";
+		
+		/// <summary>
+		/// Build action for Android Lint configuration files.
+		/// </summary>
 		public const string AndroidLintConfig = "AndroidLintConfig";
+		
+		/// <summary>
+		/// Build action for native library files (.so) for Android.
+		/// </summary>
 		public const string AndroidNativeLibrary = "AndroidNativeLibrary";
+		
+		/// <summary>
+		/// Internal build action for Android member remapping metadata.
+		/// </summary>
 		public const string _AndroidRemapMembers = "_AndroidRemapMembers";
+		
+		/// <summary>
+		/// Build action for ProGuard configuration files.
+		/// </summary>
 		public const string ProguardConfiguration = "ProguardConfiguration";
+		
+		/// <summary>
+		/// Build action for XML transform files.
+		/// </summary>
 		public const string TransformFile = "TransformFile";
+		
+		/// <summary>
+		/// Build action for input JAR files in Java binding projects.
+		/// </summary>
 		public const string InputJar = "InputJar";
+		
+		/// <summary>
+		/// Build action for reference JAR files in Java binding projects.
+		/// </summary>
 		public const string ReferenceJar = "ReferenceJar";
+		
+		/// <summary>
+		/// Build action for embedded JAR files in Java binding projects.
+		/// </summary>
 		public const string EmbeddedJar = "EmbeddedJar";
+		
+		/// <summary>
+		/// Build action for embedded native library files.
+		/// </summary>
 		public const string EmbeddedNativeLibrary = "EmbeddedNativeLibrary";
+		
+		/// <summary>
+		/// Build action for embedded reference JAR files in Java binding projects.
+		/// </summary>
 		public const string EmbeddedReferenceJar = "EmbeddedReferenceJar";
+		
+		/// <summary>
+		/// Build action for Android library project ZIP files.
+		/// </summary>
 		public const string LibraryProjectZip = "LibraryProjectZip";
+		
+		/// <summary>
+		/// Build action for Android library project properties files.
+		/// </summary>
 		public const string LibraryProjectProperties = "LibraryProjectProperties";
 	}
 }

src/Xamarin.Android.Build.Tasks/Tests/Xamarin.ProjectTools/Android/AndroidLinkMode.cs

@@ -2,17 +2,54 @@
 
 namespace Xamarin.ProjectTools
 {
-
+	/// <summary>
+	/// Specifies the Android linker mode for IL trimming in Xamarin.Android projects.
+	/// Determines how aggressively the linker removes unused code to reduce application size.
+	/// </summary>
+	/// <remarks>
+	/// The Android linker analyzes IL code and removes unused methods, types, and assemblies
+	/// to reduce the final application size. Different modes provide different levels of
+	/// optimization with varying degrees of safety.
+	/// </remarks>
+	/// <seealso cref="TrimMode"/>
 	public enum AndroidLinkMode
 	{
+		/// <summary>
+		/// No linking is performed. All code is preserved in the final application.
+		/// </summary>
 		None,
+		
+		/// <summary>
+		/// Only Android SDK and BCL assemblies are linked. User assemblies are preserved.
+		/// </summary>
 		SdkOnly,
+		
+		/// <summary>
+		/// All assemblies including user assemblies are linked for maximum size reduction.
+		/// </summary>
 		Full,
 	}
 
+	/// <summary>
+	/// Specifies the trim mode for .NET trimming in modern .NET Android projects.
+	/// Determines the aggressiveness of IL trimming for size optimization.
+	/// </summary>
+	/// <remarks>
+	/// Trim modes are used in .NET 6+ Android projects to control how the .NET trimmer
+	/// removes unused code. This is similar to but distinct from the traditional
+	/// Xamarin.Android linker modes.
+	/// </remarks>
+	/// <seealso cref="AndroidLinkMode"/>
 	public enum TrimMode
 	{
+		/// <summary>
+		/// Partial trimming removes some unused code while preserving reflection safety.
+		/// </summary>
 		Partial,
+		
+		/// <summary>
+		/// Full trimming aggressively removes unused code for maximum size reduction.
+		/// </summary>
 		Full,
 	}
 }

src/Xamarin.Android.Build.Tasks/Tests/Xamarin.ProjectTools/Android/XamarinAndroidApplicationProject.cs

@@ -10,6 +10,23 @@
 
 namespace Xamarin.ProjectTools
 {
+	/// <summary>
+	/// Represents a Xamarin.Android application project for testing purposes.
+	/// This class provides a concrete implementation of an Android application project
+	/// with default templates, resources, and configuration suitable for test scenarios.
+	/// </summary>
+	/// <remarks>
+	/// This class extends <see cref="XamarinAndroidCommonProject"/> to provide a complete
+	/// Android application project setup including:
+	/// - Default MainActivity template
+	/// - Default layout resources
+	/// - Android manifest configuration
+	/// - Application-specific MSBuild properties
+	/// Used for testing build scenarios, deployment, and application-level functionality.
+	/// </remarks>
+	/// <seealso cref="XamarinAndroidCommonProject"/>
+	/// <seealso cref="XamarinAndroidLibraryProject"/>
+	/// <seealso cref="XamarinAndroidBindingProject"/>
 	public class XamarinAndroidApplicationProject : XamarinAndroidCommonProject
 	{
 		const string default_strings_xml = @"<?xml version=""1.0"" encoding=""utf-8""?>
@@ -36,6 +53,17 @@ static XamarinAndroidApplicationProject ()
 
 		}
 
+		/// <summary>
+		/// Initializes a new instance of the XamarinAndroidApplicationProject class.
+		/// Creates a complete Android application project with default templates and configuration.
+		/// </summary>
+		/// <param name="debugConfigurationName">The name for the debug configuration (default: "Debug").</param>
+		/// <param name="releaseConfigurationName">The name for the release configuration (default: "Release").</param>
+		/// <param name="packageName">The Android package name for the application. If empty, uses the caller's method name.</param>
+		/// <remarks>
+		/// Sets up the project as an executable (OutputType = "Exe") with nullable reference types enabled,
+		/// default Android support properties, and includes standard application templates.
+		/// </remarks>
 		public XamarinAndroidApplicationProject (string debugConfigurationName = "Debug", string releaseConfigurationName = "Release", [CallerMemberName] string packageName = "")
 			: base (debugConfigurationName, releaseConfigurationName)
 		{

src/Xamarin.Android.Build.Tasks/Tests/Xamarin.ProjectTools/Android/XamarinAndroidProject.cs

@@ -7,16 +7,42 @@
 
 namespace Xamarin.ProjectTools
 {
+	/// <summary>
+	/// Abstract base class for Xamarin.Android projects in the test framework.
+	/// Extends <see cref="DotNetXamarinProject"/> to provide Android-specific functionality and defaults.
+	/// </summary>
+	/// <remarks>
+	/// This class serves as the foundation for concrete Android project types like
+	/// <see cref="XamarinAndroidApplicationProject"/> and <see cref="XamarinAndroidLibraryProject"/>.
+	/// It sets up Android-specific default properties and language settings.
+	/// </remarks>
+	/// <seealso cref="DotNetXamarinProject"/>
+	/// <seealso cref="XamarinAndroidApplicationProject"/>
+	/// <seealso cref="XamarinAndroidLibraryProject"/>
+	/// <seealso cref="XamarinAndroidProjectLanguage"/>
 	public abstract class XamarinAndroidProject : DotNetXamarinProject
 	{
+		/// <summary>
+		/// Initializes a new instance of the XamarinAndroidProject class with the specified configuration names.
+		/// Sets the default language to C# and output type to Library.
+		/// </summary>
+		/// <param name="debugConfigurationName">The name for the debug configuration (default: "Debug").</param>
+		/// <param name="releaseConfigurationName">The name for the release configuration (default: "Release").</param>
+		/// <seealso cref="XamarinAndroidProjectLanguage"/>
+		/// <seealso cref="KnownProperties.OutputType"/>
 		protected XamarinAndroidProject (string debugConfigurationName = "Debug", string releaseConfigurationName = "Release")
 			: base (debugConfigurationName, releaseConfigurationName)
 		{
 			Language = XamarinAndroidProjectLanguage.CSharp;
 			SetProperty (KnownProperties.OutputType, "Library");
 		}
 
-
+		/// <summary>
+		/// Gets the language settings specific to Xamarin.Android projects.
+		/// </summary>
+		/// <returns>The Android-specific language configuration.</returns>
+		/// <seealso cref="XamarinAndroidProjectLanguage"/>
+		/// <seealso cref="Language"/>
 		public XamarinAndroidProjectLanguage XamarinAndroidLanguage {
 			get { return (XamarinAndroidProjectLanguage) Language; }
 		}

src/Xamarin.Android.Build.Tasks/Tests/Xamarin.ProjectTools/Common/BuildActions.cs

@@ -7,15 +7,58 @@
 
 namespace Xamarin.ProjectTools
 {
+	/// <summary>
+	/// Contains constant values for commonly used MSBuild item types (build actions).
+	/// These constants provide a centralized way to reference standard build actions
+	/// used in project files and build items.
+	/// </summary>
+	/// <remarks>
+	/// These build actions correspond to the standard MSBuild item types that determine
+	/// how files are processed during the build. Used with <see cref="BuildItem"/> 
+	/// and throughout the test project system.
+	/// </remarks>
+	/// <seealso cref="BuildItem"/>
+	/// <seealso cref="AndroidBuildActions"/>
 	public static class BuildActions
 	{
+		/// <summary>
+		/// Build action for files that should be included in the project but not compiled or processed.
+		/// </summary>
 		public const string None = "None";
+		
+		/// <summary>
+		/// Build action for references to other projects in the same solution.
+		/// </summary>
 		public const string ProjectReference = "ProjectReference";
+		
+		/// <summary>
+		/// Build action for NuGet package references.
+		/// </summary>
 		public const string PackageReference = "PackageReference";
+		
+		/// <summary>
+		/// Build action for assembly references.
+		/// </summary>
 		public const string Reference = "Reference";
+		
+		/// <summary>
+		/// Build action for source code files that should be compiled.
+		/// </summary>
 		public const string Compile = "Compile";
+		
+		/// <summary>
+		/// Build action for files that should be embedded as resources in the assembly.
+		/// </summary>
 		public const string EmbeddedResource = "EmbeddedResource";
+		
+		/// <summary>
+		/// Build action for content files that should be copied to the output directory.
+		/// </summary>
 		public const string Content = "Content";
+		
+		/// <summary>
+		/// Build action for folders in the project structure.
+		/// </summary>
 		public const string Folder = "Folder";
 	}
 }