refact the tool and add xml doc support

[lei9444]

This pull request introduces significant improvements and refactoring to the winrt-meta code generation tool, focusing on modularizing codegen logic, introducing a language abstraction layer, and enhancing generated documentation for both TypeScript and Python outputs. The changes improve maintainability, extensibility, and code clarity, especially for handling language-specific code generation and documentation.

Key changes include:

Language Abstraction & Modularization

• Introduced a new Lang trait (lang.rs) that abstracts language-specific code generation logic, enabling TypeScript and Python codegen to share orchestrator logic and making it easier to add new languages in the future. Implementations for TypeScript (ts_lang.rs) and Python (py_lang.rs) are provided, and orchestrators are refactored to use this trait. [1] [2]
• Refactored codegen modules for better separation of concerns, adding new files for imports (imports.rs), naming helpers (naming.rs), and other codegen utilities, and updating the main module to re-export these. [1] [2] [3]

Improved Code Generation & Type Handling

• Added helpers to collect generic types and imports used in method signatures and class/interface definitions, improving the accuracy of generated import statements and generic handling in output code.
• Exposed py_array_element_type as a public helper for use in other modules.

Enhanced Documentation Generation

• Added automatic JSDoc and Python docstring generation for methods in generated TypeScript and Python output. These doc comments are now included in the output for static methods, factory methods, and instance methods, leveraging XML documentation from metadata. [1] [2] [3] [4] [5] [6]

Bug Fixes & Minor Improvements

• Fixed the IAsyncOperationWithProgress IID computation for structs containing enums, ensuring correct type signatures and interface identification.
• Added the roxmltree dependency for XML documentation parsing.
• Removed unnecessary Python package init file creation from the e2e test script.

---

References:

• Language abstraction & modularization: [1] [2] [3] [4] [5]
• Improved code generation & type handling: [1] [2]
• Enhanced documentation generation: [1] [2] [3] [4] [5] [6]
• Bug fixes & minor improvements: [1] [2] [3]

[Copilot]

Pull request overview

This PR refactors the tools/winrt-meta code generation tool to make language-specific generation more modular (via a Lang abstraction and split helper modules), and adds XML documentation parsing/formatting to enrich generated TypeScript JSDoc and Python docstrings. It also introduces optional Python .pyi stub emission and extends snapshot coverage to guard the refactor and new outputs.

Changes:

• Introduce a Lang trait with TypeScript/Python implementations, and split shared codegen logic into focused helper modules (imports, naming, signatures, structs, etc.).
• Add XML doc parsing (DocTable) from sibling .xml files and plumb docs into generated TS/Python outputs (including enum/type docs).
• Add --pyi for Python generation to emit .pyi stubs and py.typed, plus new snapshot fixtures/tests for .py and .pyi outputs.

Reviewed changes

Copilot reviewed 35 out of 36 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tools/winrt-meta/tests/snapshots/uri_pyi/www_form_url_decoder.pyi	New snapshot for generated Python stubs for WwwFormUrlDecoder.
tools/winrt-meta/tests/snapshots/uri_pyi/uri.pyi	New snapshot for generated Python stubs for Uri and related interfaces.
tools/winrt-meta/tests/snapshots/uri_pyi/i_uri_runtime_class_with_absolute_canonical_uri.pyi	New snapshot for generated interface stub module.
tools/winrt-meta/tests/snapshots/uri_pyi/i_stringable.pyi	New snapshot for generated IStringable stub module.
tools/winrt-meta/tests/snapshots/uri_pyi/init.pyi	New snapshot for generated stub package index.
tools/winrt-meta/tests/snapshots/uri_py/www_form_url_decoder.py	New snapshot for generated Python implementation module.
tools/winrt-meta/tests/snapshots/uri_py/uri.py	New snapshot for generated Python implementation module.
tools/winrt-meta/tests/snapshots/uri_py/i_uri_runtime_class_with_absolute_canonical_uri.py	New snapshot for generated Python interface module.
tools/winrt-meta/tests/snapshots/uri_py/i_stringable.py	New snapshot for generated Python interface module.
tools/winrt-meta/tests/snapshots/uri_py/init.py	New snapshot for generated Python package index.
tools/winrt-meta/tests/snapshot_test.rs	Adds snapshot tests for Python .py and .pyi outputs (in addition to TS).
tools/winrt-meta/src/xml_doc.rs	Adds XML doc parsing, normalization, lookup, and application onto meta structures.
tools/winrt-meta/src/types.rs	Extends enum metadata to carry XML doc and deprecation info (incl. per-member docs).
tools/winrt-meta/src/meta.rs	Extends meta structures with raw CLR names/signature keys and doc/deprecation fields for doc lookup and emission.
tools/winrt-meta/src/main.rs	Loads sibling XML docs, applies them to parsed metadata, and adds --pyi output behavior.
tools/winrt-meta/src/lib.rs	Exposes the new xml_doc module from the crate.
tools/winrt-meta/src/codegen/xml_text.rs	Formats normalized docs into JSDoc and Python docstrings; includes escaping + tests.
tools/winrt-meta/src/codegen/typescript.rs	Emits JSDoc for types/enums and uses new doc fields in generated TS output.
tools/winrt-meta/src/codegen/ts_lang.rs	Adds TypeScript implementation of the new Lang trait.
tools/winrt-meta/src/codegen/structs_helpers.rs	Extracts struct collection + field helper logic into a shared module.
tools/winrt-meta/src/codegen/sig.rs	Consolidates signature building, wrapping, return conversion, and registration helpers.
tools/winrt-meta/src/codegen/python_stub.rs	Adds Python .pyi stub generator for classes/interfaces/enums (and indices).
tools/winrt-meta/src/codegen/python.rs	Emits Python docstrings for types and enums; uses shared method reordering helper.
tools/winrt-meta/src/codegen/py_shared.rs	Adds shared Python helper for ordering getters before setters.
tools/winrt-meta/src/codegen/py_method.rs	Adds method-level Python docstring emission using XML docs.
tools/winrt-meta/src/codegen/py_lang.rs	Adds Python implementation of the new Lang trait.
tools/winrt-meta/src/codegen/naming.rs	Extracts naming helpers (camel/snake case, reserved word handling).
tools/winrt-meta/src/codegen/mod.rs	Re-exports/surfaces the new refactored codegen modules.
tools/winrt-meta/src/codegen/method.rs	Adds method-level JSDoc emission using XML docs.
tools/winrt-meta/src/codegen/lang.rs	Introduces the Lang trait + basic object-safety tests.
tools/winrt-meta/src/codegen/imports.rs	Extracts import + generic collection logic for orchestrators.
tools/winrt-meta/src/codegen/common.rs	Converts common into a backward-compatible facade re-exporting refactored helpers.
tools/winrt-meta/Cargo.toml	Adds roxmltree dependency for XML doc parsing.
tests/e2e_test.ps1	Removes redundant __init__.py creation in e2e flow.
TODO.md	Marks async IID enum-in-struct issue as completed with updated explanation.
Cargo.lock	Locks roxmltree dependency addition.