docs(passes): Document NormalizeReturnOrder pass#1234
Merged
Hzfengsy merged 2 commits intohw-native-sys:mainfrom Apr 30, 2026
Merged
docs(passes): Document NormalizeReturnOrder pass#1234Hzfengsy merged 2 commits intohw-native-sys:mainfrom
Hzfengsy merged 2 commits intohw-native-sys:mainfrom
Conversation
Adds the missing per-pass doc for slot hw-native-sys#20 (`NormalizeReturnOrder`) in both EN and ZH, mirroring the established structure of the surrounding pass docs (overview, API table, properties, two-step algorithm, constraints, before/after example, implementation pointers, related links). Updates `pass-doc-ordering.md` to mark slot 20 as documented, and converts existing `NormalizeReturnOrder` mentions in pass-manager, LowerPipelineLoops, and codegen overviews into links to the new file. Fixes hw-native-sys#1168
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
✅ Files skipped from review due to trivial changes (3)
📝 WalkthroughWalkthroughAdds a dedicated English and Chinese developer doc for the NormalizeReturnOrder pass, updates the pass-ordering registry to reference that doc, and replaces inline mentions with links to the new pass page across related documentation files. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related issues
Possibly related PRs
Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Review rate limit: 0/1 reviews remaining, refill in 60 minutes.Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces comprehensive documentation for the NormalizeReturnOrder pass in both English and Chinese. It includes a new dedicated documentation file detailing the pass's algorithm, constraints, and implementation, while also updating cross-references in the codegen and pass manager documentation. The review feedback identifies technical inaccuracies in the description of the Step B remapping logic and highlights a slot number inconsistency in the pipeline position description that needs to be aligned with the project's pass registry.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/zh-cn/dev/passes/21-lower_pipeline_loops.md`:
- Line 13: Update the Chinese doc's pipeline-position sentence to match the
English wording by adding that this pass is also before CanonicalizeIOOrder:
modify the line mentioning NormalizeReturnOrder and InitMemRef (slot 20.5) to
read that it is after `NormalizeReturnOrder` and before `CanonicalizeIOOrder`
and `InitMemRef` (e.g., append “并且在 `CanonicalizeIOOrder` 之前” so the sentence
references `NormalizeReturnOrder`, `CanonicalizeIOOrder`, and `InitMemRef`).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: 298a6b6f-90b7-4c4c-8c2d-7cc34930cccf
📒 Files selected for processing (11)
.claude/rules/pass-doc-ordering.mddocs/en/dev/codegen/00-pto_codegen.mddocs/en/dev/codegen/01-orchestration_codegen.mddocs/en/dev/passes/00-pass_manager.mddocs/en/dev/passes/20-normalize_return_order.mddocs/en/dev/passes/21-lower_pipeline_loops.mddocs/zh-cn/dev/codegen/00-pto_codegen.mddocs/zh-cn/dev/codegen/01-orchestration_codegen.mddocs/zh-cn/dev/passes/00-pass_manager.mddocs/zh-cn/dev/passes/20-normalize_return_order.mddocs/zh-cn/dev/passes/21-lower_pipeline_loops.md
Contributor
There was a problem hiding this comment.
Pull request overview
Adds the missing per-pass documentation for NormalizeReturnOrder and updates cross-references so related docs link to the new pass doc, keeping the pass-doc registry in sync with the pipeline.
Changes:
- Add new per-pass docs for
NormalizeReturnOrderin both English and Chinese. - Update
.claude/rules/pass-doc-ordering.mdto register the slot-20 doc filename. - Replace bare
NormalizeReturnOrdermentions with links in pass-manager, LowerPipelineLoops, and codegen overview/orchestration docs (EN + ZH).
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/en/dev/passes/20-normalize_return_order.md | New detailed per-pass documentation for NormalizeReturnOrder (EN). |
| docs/zh-cn/dev/passes/20-normalize_return_order.md | New detailed per-pass documentation for NormalizeReturnOrder (ZH). |
| .claude/rules/pass-doc-ordering.md | Update registry to point slot 20 to the new doc file. |
| docs/en/dev/passes/00-pass_manager.md | Link NormalizeReturnOrder mention to the new pass doc. |
| docs/zh-cn/dev/passes/00-pass_manager.md | Link NormalizeReturnOrder mention to the new pass doc. |
| docs/en/dev/passes/21-lower_pipeline_loops.md | Link pipeline-position reference to NormalizeReturnOrder doc. |
| docs/zh-cn/dev/passes/21-lower_pipeline_loops.md | Link pipeline-position reference to NormalizeReturnOrder doc. |
| docs/en/dev/codegen/00-pto_codegen.md | Link NormalizeReturnOrder reference to the new pass doc. |
| docs/zh-cn/dev/codegen/00-pto_codegen.md | Link NormalizeReturnOrder reference to the new pass doc. |
| docs/en/dev/codegen/01-orchestration_codegen.md | Link NormalizeReturnOrder reference to the new pass doc. |
| docs/zh-cn/dev/codegen/01-orchestration_codegen.md | Link NormalizeReturnOrder reference to the new pass doc. |
- Convert remaining British spellings (normalisation/canonicalises/ materialises/normalised) in 20-normalize_return_order.md (EN) to American to match the surrounding docs (Copilot review). - Replace the "transformed node" Constraints row in EN+ZH with a clearer rationale: the mutator preserves Var node identity, so the operand pointer stays valid as a key in `reordered_tuple_vars_` (Gemini review). - ZH 21-lower_pipeline_loops.md "Pipeline position" sentence now mentions both `CanonicalizeIOOrder` and `InitMemRef` to match the EN wording (CodeRabbit review).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the missing per-pass documentation for
NormalizeReturnOrder(slot#20 in the
Defaultstrategy) in both English and Chinese, fills in thepass-doc-ordering.mdregistry, and converts existing bare mentions inthe pass-manager /
LowerPipelineLoops/ codegen overview docs intolinks to the new file.
docs/en/dev/passes/20-normalize_return_order.md(266 lines) anddocs/zh-cn/dev/passes/20-normalize_return_order.md(246 lines)cover purpose & pipeline position, required/produced/invalidated
IRProperty, the C++ ↔ Python API table, the two-phase algorithm(InCore rewrite via
BuildReturnToParamMapping/ComputeReturnPermutation/ReorderReturns, then call-siteTupleGetItemExprremap viaTupleIndexPermutationMutator), anend-to-end before/after example mirroring
test_swapped_returns_reordered, and pointers to the implementation.claude/rules/pass-doc-ordering.mdslot 20 row updated fromno doc yet →
20-normalize_return_order.mdNormalizeReturnOrdermentions inpasses/00-pass_manager.md,passes/21-lower_pipeline_loops.md,codegen/00-pto_codegen.md, andcodegen/01-orchestration_codegen.md(EN + ZH) now link to the new doc
Testing
python tests/lint/check_english_only.pypassesinclude/pypto/ir/transforms/passes.h:460,include/pypto/ir/transforms/pass_properties.h:161,python/bindings/modules/passes.cpp:287,python/pypto/pypto_core/passes.pyi:296,python/pypto/ir/pass_manager.py:148Related Issues
Fixes #1168 (parent: #1161)