Commit bb13eaa
authored
doc: add dataclass reflection guide and update related docs (#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).1 parent dad4c40 commit bb13eaa
File tree
5 files changed
+477
-3
lines changed- docs
- concepts
- guides
5 files changed
+477
-3
lines changed| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
393 | 393 | | |
394 | 394 | | |
395 | 395 | | |
396 | | - | |
| 396 | + | |
397 | 397 | | |
398 | 398 | | |
399 | 399 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
92 | 92 | | |
93 | 93 | | |
94 | 94 | | |
95 | | - | |
| 95 | + | |
| 96 | + | |
96 | 97 | | |
97 | 98 | | |
98 | 99 | | |
| |||
292 | 293 | | |
293 | 294 | | |
294 | 295 | | |
| 296 | + | |
| 297 | + | |
295 | 298 | | |
296 | 299 | | |
297 | 300 | | |
| |||
338 | 341 | | |
339 | 342 | | |
340 | 343 | | |
| 344 | + | |
| 345 | + | |
| 346 | + | |
341 | 347 | | |
342 | 348 | | |
343 | 349 | | |
| |||
0 commit comments