The marshal methods system is a critical performance optimization for Android applications that generates native code bridges between .NET and Java/JNI. However, the code lacked comprehensive documentation, making it difficult for developers to understand, maintain, and extend.

Changes Made

This PR adds extensive XML documentation and inline comments to the core marshal methods pipeline, covering:

🔍 Classification & Analysis Layer

• MarshalMethodsClassifier.cs - The core engine that analyzes .NET methods and determines marshal method compatibility

  • Documents complex signature matching logic and [UnmanagedCallersOnly] validation
  • Explains standard handler pattern recognition and connector method resolution
  • Details blittable type checking and workaround generation strategies

• MarshalMethodsHelpers.cs - Utility methods for blittable type analysis with references to Microsoft documentation

📊 Collection & Management Layer

• MarshalMethodsCollection.cs - Orchestrates assembly scanning and method classification

  • Documents integration with JavaInterop type scanner
  • Explains special case handling for framework methods like TypeManager.n_Activate
  • Details Kotlin method filtering and inheritance scenarios

• MarshalMethodsState.cs & ManagedMarshalMethodsLookupInfo.cs - State management and runtime lookup infrastructure

⚙️ Build Task Orchestration

• RewriteMarshalMethods.cs - MSBuild task that rewrites assemblies to use marshal methods

  • Documents assembly modification workflow and pipeline state management
  • Explains managed lookup table generation and ordering dependencies

• GenerateNativeMarshalMethodSources.cs - MSBuild task that generates LLVM IR code

  • Documents runtime-specific code generation (MonoVM vs CoreCLR)
  • Explains multi-ABI support and P/Invoke preservation

Documentation Features

✨ Comprehensive Coverage: Every public, protected, internal, and private member now has detailed XML documentation explaining purpose, parameters, return values, and exceptions

✨ Complex Algorithm Explanations: Inline documentation within methods explains intricate logic flows and decision points

✨ System Architecture: Clear explanations of component interactions and build pipeline integration

✨ Error Handling: Documentation of error conditions, logging patterns, and debugging aids

Example

Before:

bool IsStandardHandler (TypeDefinition topType, ConnectorInfo connector, MethodDefinition registeredMethod, MethodDefinition implementedMethod, string jniName, string jniSignature, [NotNullWhen (true)] out MarshalMethodEntry? marshalMethodEntry)
{
    // 50+ lines of complex logic with minimal comments
}

After:

/// <summary>
/// Determines whether a method follows the "standard handler" pattern and can be converted to a marshal method.
/// The standard handler pattern involves a native callback method, a connector method that returns a delegate,
/// and optionally a delegate backing field. This method performs extensive validation to ensure all
/// components exist and are compatible.
/// </summary>
/// <param name="topType">The top-level type that owns this method.</param>
/// <param name="connector">Information about the connector method parsed from the [Register] attribute.</param>
/// <param name="registeredMethod">The method that was registered with the [Register] attribute.</param>
/// <param name="implementedMethod">The actual method implementation.</param>
/// <param name="jniName">The JNI method name from the [Register] attribute.</param>
/// <param name="jniSignature">The JNI method signature from the [Register] attribute.</param>
/// <param name="marshalMethodEntry">
/// When this method returns true, contains the marshal method entry for the convertible method.
/// When this method returns false, this parameter is null.
/// </param>
/// <returns>true if the method follows the standard handler pattern; false otherwise.</returns>
bool IsStandardHandler (TypeDefinition topType, ConnectorInfo connector, MethodDefinition registeredMethod, MethodDefinition implementedMethod, string jniName, string jniSignature, [NotNullWhen (true)] out MarshalMethodEntry? marshalMethodEntry)
{
    // Method body with detailed inline comments explaining each validation step
}

This documentation significantly improves the maintainability and approachability of the marshal methods system, making it easier for developers to understand this critical Android optimization.

Fixes #10435.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.