docs(allocator): reformat comments in Arena#21448
Conversation
How to use the Graphite Merge QueueAdd either label to this PR to merge it via the merge queue:
You must have a Graphite account in order to use the merge queue. Sign up using this link. An organization admin has enabled the Graphite Merge Queue in this repository. Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue. This stack of pull requests is managed by Graphite. Learn more about stacking. |
github-actions
Bot
added
A-allocator
Merge activity
|
There was a problem hiding this comment.
Pull request overview
This PR reformats and clarifies Rust doc/comments across the oxc_allocator::arena implementation, aiming to improve readability and correct small documentation issues without changing runtime behavior.
Changes:
- Reflow and standardize doc/comment formatting across
Arenamodules (single-line wrapping, punctuation, wording). - Improve/adjust rustdoc link usage and section text in
Arenadocumentation. - Convert some internal comments into rustdoc comments (e.g., constants/fields) to better surface intent in generated docs.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| crates/oxc_allocator/src/arena/tests.rs | Minor comment wording/formatting updates in unit tests. |
| crates/oxc_allocator/src/arena/mod.rs | Reflow/clarify top-level Arena rustdoc and some internal comments. |
| crates/oxc_allocator/src/arena/from_raw_parts.rs | Rewrapped SAFETY/docs comments for readability. |
| crates/oxc_allocator/src/arena/drop.rs | Reflowed reset docs and improved link reference to top-level docs. |
| crates/oxc_allocator/src/arena/create.rs | Converted several explanatory comments into rustdoc; reflowed constructor docs. |
| crates/oxc_allocator/src/arena/chunks.rs | Reflowed iterator/docs text and updated intra-doc links. |
| crates/oxc_allocator/src/arena/bumpalo_alloc.rs | Reflowed upstream-derived docs/comments for consistency. |
| crates/oxc_allocator/src/arena/alloc_impl.rs | Reflowed inline comments in allocation logic. |
| crates/oxc_allocator/src/arena/alloc.rs | Reflowed allocation method docs and tweaked wording. |
| // own function instead of inlining it into the surrounding code. | ||
| // Ideally we want LLVM to always realize that doing a stack allocation is unnecessary and optimize | ||
| // the code so it writes directly into the heap instead. It seems we get it to realize this most | ||
| // consistently if we put this critical line into it's own function instead of inlining it into the |
There was a problem hiding this comment.
Spelling/grammar: “into it's own function” should be “into its own function”.
| // consistently if we put this critical line into it's own function instead of inlining it into the | |
| // consistently if we put this critical line into its own function instead of inlining it into the |
| @@ -300,26 +283,23 @@ impl<const MIN_ALIGN: usize> Arena<MIN_ALIGN> { | |||
| // | a | b | c | . | . | | |||
| // +-----+-----+-----+-----+-----+ | |||
| // | |||
| // But we MUST NOT have overlapping ranges because we use | |||
| // `copy_nonoverlapping` below! Therefore, we round the division | |||
| // up to avoid this issue. | |||
| // But we MUST NOT have overlapping ranges because we use `copy_nonoverlapping` below. | |||
| // Therefore, we round the division up to avoid this issue. | |||
There was a problem hiding this comment.
Comment typos make this explanation harder to follow: “And the the check…” and “we are have overlapping ranges” should be corrected (e.g. “And the check…” / “we have overlapping ranges”).
| /// Default chunk size for a new `Arena`, minus the size of the footer. | ||
| /// | ||
| /// The actual size of the first allocation is going to be a bit smaller than the goal. | ||
| /// We need to make room for the footer, and we also need take the alignment into account. |
There was a problem hiding this comment.
The doc comment for DEFAULT_CHUNK_SIZE_WITHOUT_FOOTER says it’s “minus the size of the footer”, but the value is FIRST_ALLOCATION_GOAL - OVERHEAD where OVERHEAD also includes malloc overhead and alignment rounding. Please adjust the wording to match what’s actually subtracted (overhead, not just the footer).
| /// Default chunk size for a new `Arena`, minus the size of the footer. | |
| /// | |
| /// The actual size of the first allocation is going to be a bit smaller than the goal. | |
| /// We need to make room for the footer, and we also need take the alignment into account. | |
| /// Default chunk size for a new `Arena`, minus allocation overhead. | |
| /// | |
| /// The actual size of the first allocation is going to be a bit smaller than the goal. | |
| /// We need to make room for overhead such as the footer, allocator overhead, and alignment. |
|
|
||
| /// Allocates a new slice of size `len` slice into this `Arena` and return an | ||
| /// exclusive reference to the copy. | ||
| /// Allocate a new slice of size `len` into this `Arena`. Return an exclusive reference to the clone. |
There was a problem hiding this comment.
Minor doc wording issue: this function returns a slice (&mut [T]), so “Return an exclusive reference to the clone” is misleading. Consider rephrasing to “Returns an exclusive reference to the slice” (filled with value.clone()) and fix the “Return” -> “Returns” grammar.
| /// Allocate a new slice of size `len` into this `Arena`. Return an exclusive reference to the clone. | |
| /// Allocate a new slice of size `len` into this `Arena`. Returns an exclusive reference to the slice. |
| // own function instead of inlining it into the surrounding code. | ||
| // Ideally we want LLVM to always realize that doing a stack allocation is unnecessary and optimize | ||
| // the code so it writes directly into the heap instead. It seems we get it to realize this most | ||
| // consistently if we put this critical line into it's own function instead of inlining it into the |
There was a problem hiding this comment.
Spelling/grammar: “into it's own function” should be “into its own function”.
| // consistently if we put this critical line into it's own function instead of inlining it into the | |
| // consistently if we put this critical line into its own function instead of inlining it into the |
41849d8 to
c5b19bb
Compare
Merging this PR will not alter performance
Comparing 
Footnotes
|
### 💥 BREAKING CHANGES - 24fb7eb allocator: [**BREAKING**] Rename `Box` and `Vec` methods (#21395) (overlookmotel) ### 🚀 Features - ce5072d parser: Support `turbopack` magic comments (#20803) (Kane Wang) - f5deb55 napi/transform: Expose `optimizeConstEnums` and `optimizeEnums` options (#21388) (Dunqing) - 24b03de data_structures: Introduce `NonNullConst` and `NonNullMut` pointer types (#21425) (overlookmotel) ### 🐛 Bug Fixes - d7a359a ecmascript: Treat update expressions as unconditionally side-effectful (#21456) (Dunqing) - 56af2f4 transformer/async-to-generator: Correct scope of inferred named FE in async-to-generator (#21458) (Dunqing) - b3ed467 minifier: Avoid illegal `var;` when folding unused arguments copy loop (#21421) (fazba) - b0e8f13 minifier: Preserve `var` inside `catch` with same-named parameter (#21366) (Dunqing) - 4fb73a7 transformer/typescript: Preserve execution order for accessor with `useDefineForClassFields: false` (#21369) (Dunqing) ### ⚡ Performance - da3cc16 parser: Refactor out `LexerContext` (#21275) (Ulrich Stark) ### 📚 Documentation - c5b19bb allocator: Reformat comments in `Arena` (#21448) (overlookmotel) - 091e88e lexer: Update doc comment about perf benefit of reading through references (#21423) (overlookmotel) - 922cbee allocator: Remove references to "bump" from comments (#21397) (overlookmotel) Co-authored-by: Dunqing <[email protected]>
Comments-only change. Reformat comments in
Arenacode, and correct a few small mistakes.