junrushao opened a new pull request, #494:
URL: https://github.com/apache/tvm-ffi/pull/494
## Summary
Add a comprehensive guide for the dataclass-style reflection system
(`ObjectDef`, field traits, auto-init, deep copy, repr, hashing, comparison)
and update the Sphinx documentation configuration and cross-references.
## Changes
### New documentation
- **`docs/guides/dataclass_reflection.rst`** — A 467-line guide covering:
- Quick start: defining a C++ object with `ObjectDef`, using it from
Python with full dataclass semantics.
- Auto-generated constructors: how `__ffi_init__` is synthesized from
reflected fields, including positional, optional, and keyword-only parameter
ordering.
- Field traits reference: `refl::default_()`, `refl::default_factory()`,
`refl::kw_only()`, `refl::init()`, `refl::repr()`, `refl::hash()`,
`refl::compare()`, `refl::Metadata`.
- Dataclass operations: `DeepCopy`, `ReprPrint`, `RecursiveHash`,
`RecursiveEq` with behavioral details (iterative DFS, cycle handling, DAG
caching).
- Custom hooks via `TypeAttrDef` for hash, equality, comparison, and repr
overrides.
- Python `c_class` decorator and `@register_object` delegation.
- Inheritance semantics for field composition across parent/child object
hierarchies.
### Sphinx configuration updates (`docs/conf.py`)
- Exclude `tvm::ffi::reflection::default_` and
`tvm::ffi::reflection::default_factory` from Doxygen symbol output (these are
user-facing helpers that cause Doxygen parse noise).
- Fix `_link_inherited_members` to rewrite `.CObject` references as
`.Object` in cross-reference links, correcting broken autodoc inherited-member
links.
- Add `_move`, `__move_handle_from__`, and `__init_handle_by_constructor__`
to `_autodoc_always_show`, ensuring these low-level Object lifecycle methods
appear in auto-generated API docs.
### Cross-reference fixes in existing docs
- **`docs/concepts/object_and_class.rst`**: Update `refl::DefaultValue(0)`
to `refl::default_(0)` to match the current preferred API name.
- **`docs/guides/export_func_cls.rst`**: Replace broken
`:cpp:class:\`tvm::ffi::reflection::init\`` Sphinx cross-reference with inline
code literal `` ``init<Args...>()`` `` (the template alias does not resolve as
a Doxygen class).
### TOC integration
- **`docs/index.rst`**: Insert `guides/dataclass_reflection.rst` into the
Guides toctree between `export_func_cls` and `kernel_library_guide`.
## Behavioral changes
None. This is a documentation-only change with no code modifications.
## Test evidence
Documentation-only PR; no runtime behavior is affected. The guide's code
examples are consistent with the existing C++ reflection API (`ObjectDef`,
field traits) and Python `c_class`/`register_object` implementations validated
by the existing test suite (`tests/python/test_dataclass.py`,
`tests/cpp/test_reflection.cc`).
### Untested corner cases
- Sphinx build with the new RST file has not been verified in CI yet (will
be validated by the doc-build CI job).
- The `.CObject` -> `.Object` rewrite in `_link_inherited_members` is a
string replacement; edge cases where a class legitimately contains "CObject" in
its qualified name would be incorrectly rewritten (none exist in the current
codebase).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
