Skip to content

[WIP] Add XML documentation for projected MLIR interfaces in C##182

Closed
Copilot wants to merge 1 commit into
mainfrom
copilot/generate-xml-documentation
Closed

[WIP] Add XML documentation for projected MLIR interfaces in C##182
Copilot wants to merge 1 commit into
mainfrom
copilot/generate-xml-documentation

Conversation

Copilot AI commented Apr 24, 2026

Copy link
Copy Markdown
Contributor

Thanks for asking me to work on this. I will get started on it and keep this PR's description up to date as I form a plan and make progress.


This section details on the original issue you should resolve

<issue_title>Generate XML documentation for projected MLIR interfaces and mapped C# members</issue_title>
<issue_description>## Problem

The generator now supports projecting selected MLIR interfaces into member-bearing partial C# interfaces via MLIR.NET overlay metadata. However, the generated C# surface currently loses a lot of useful explanatory context:

  • upstream Interface records often carry a description;
  • upstream InterfaceMethod records often carry method descriptions;
  • mapped C# properties and methods currently expose only names and types, without generated XML documentation that explains what they mean.

This makes the generated interface API harder to discover and use, especially for interfaces such as ShapedTypeInterface where the projected C# members are meant to feel like a real user-facing contract rather than just marker metadata.

Proposed Change

Extend the importer and generator so projected C# interfaces and their mapped members carry XML documentation derived from upstream MLIR interface metadata and MLIR.NET overlay metadata.

Specifically:

  • preserve interface-level documentation for generated partial C# interfaces;
  • preserve upstream method descriptions for mapped C# members when available;
  • allow MLIR.NET overlays to override or supplement generated member docs when the projected C# surface differs meaningfully from the upstream C++ wording;
  • emit XML doc comments for generated property- and method-shaped members.

Suggested Model/Schema Work

A reasonable first step would be:

  • continue using upstream Interface.description as the default interface summary/remarks source;
  • use upstream InterfaceMethod.description as the default member summary source;
  • add optional overlay fields for C#-specific documentation when needed, for example:
    • csharpSummary
    • csharpDescription
    • or member-level equivalents on MLIRNet_InterfaceProperty / future MLIRNet_InterfaceMethod

Exact field names can vary, but the generator should support both:

  • sensible defaults from upstream metadata;
  • explicit MLIR.NET wording when the projected C# API needs different phrasing.

Design Principles

  • Prefer upstream MLIR documentation as the default source of truth.
  • Let MLIR.NET overlays refine wording when the projected C# contract differs from the original C++ surface.
  • Keep documentation generation generic and metadata-driven.
  • Preserve existing XML doc generation style used elsewhere in the repo.
  • Do not require every mapped member to supply custom documentation.

Out Of Scope

  • Documentation generation for operation interfaces unless it falls out naturally from the same mechanism.
  • Rewriting or normalizing all upstream prose into idiomatic C# docs in the first pass.
  • Runtime behavior changes.

Acceptance Criteria

  • Generated projected interfaces emit XML documentation when interface metadata is available.
  • Generated mapped properties emit XML documentation derived from upstream method metadata when available.
  • If method-shaped interface mappings exist, generated mapped methods also emit XML documentation.
  • Overlay metadata can override or supplement generated docs for at least one interface/member.
  • Add importer and generator tests proving:
    • interface docs are preserved;
    • mapped member docs are preserved;
    • overlay docs can override defaults;
    • marker-only interfaces still behave correctly.</issue_description>

Comments on the Issue (you are @copilot in this section)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Generate XML documentation for projected MLIR interfaces and mapped C# members

2 participants