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.

Overview

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.

Changes Made

Added detailed XML documentation to 18 core classes covering approximately 150+ public/protected/internal members:

Core Project Framework

• XamarinProject - Base class for all test projects with property management, file operations, and build configuration
• XamarinAndroidProject - Android-specific project base class with Android defaults
• XamarinAndroidApplicationProject - Concrete Android application project with templates and manifest

Build System

• Builder - Base MSBuild builder with cross-platform support and build output analysis
• ProjectBuilder - Project-specific builder that manages directories, NuGet restore, and build orchestration
• BuildItem - Represents MSBuild items with nested classes for common types (Source, Content, Reference, etc.)
• BuildOutput - Provides access to build results, intermediate files, and output analysis

Property System

• Property - MSBuild property representation with conditional support
• PropertyGroup - Groups related properties with shared conditions
• ProjectLanguage - Abstract base for language-specific settings (file extensions, templates)

Constants & Enumerations

• BuildActions - Standard MSBuild item types (Compile, Content, Reference, etc.)
• AndroidBuildActions - Android-specific build actions (AndroidResource, AndroidAsset, etc.)
• AndroidLinkMode & TrimMode - Enums for IL linking and trimming configurations

Infrastructure

• Package - NuGet package reference representation
• Import - MSBuild import statements for including external targets
• TestEnvironment - Platform detection and environment utilities
• FileSystemUtils - File system operations for test cleanup
• XABuildPaths - Standard paths for build outputs and test directories

Documentation Quality

Each documented class includes:

• Comprehensive class and member descriptions explaining purpose and usage
• Complete parameter and return value documentation
• Extensive cross-references between related classes using <see cref> tags
• Usage guidance and behavioral notes
• Examples where appropriate
• Platform-specific considerations

Example

Before:

public class BuildItem
{
    public BuildItem (string buildAction, string include) { }
    public string BuildAction { get; set; }
    public Func<string> Include { get; set; }
}

After:

/// <summary>
/// Represents a build item in an MSBuild project, such as source files, resources, references, etc.
/// This class provides a flexible way to define project items with their build actions, metadata, 
/// and content for use in test projects.
/// </summary>
/// <remarks>
/// Build items correspond to MSBuild's &lt;ItemGroup&gt; elements and can represent various
/// types of project artifacts. Use the nested classes for common build item types.
/// </remarks>
/// <seealso cref="XamarinProject"/>
/// <seealso cref="BuildActions"/>
public class BuildItem
{
    /// <summary>
    /// Initializes a new instance of the BuildItem class with the specified build action and include path.
    /// </summary>
    /// <param name="buildAction">The MSBuild action for this item (e.g., "Compile", "Content", "None").</param>
    /// <param name="include">The path or identifier for the item.</param>
    /// <seealso cref="BuildActions"/>
    public BuildItem (string buildAction, string include) { }
    
    /// <summary>
    /// Gets or sets the MSBuild action for this item (e.g., "Compile", "Content", "None").
    /// </summary>
    /// <seealso cref="BuildActions"/>
    public string BuildAction { get; set; }
    
    /// <summary>
    /// Gets or sets a function that returns the include path or identifier for the item.
    /// </summary>
    public Func<string> Include { get; set; }
}

This documentation significantly improves the developer experience when working with the Xamarin.Android test framework by providing clear guidance on how to use each class and method effectively.

Fixes #10379.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.