[codegen] Test and document codegen under different layouts#3085
[codegen] Test and document codegen under different layouts#3085
Conversation
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly improves the Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## G04affc58395810ba04b941f14dfdc20563fa850b #3085 +/- ##
==========================================================================
Coverage 91.87% 91.87%
==========================================================================
Files 20 20
Lines 6057 6057
==========================================================================
Hits 5565 5565
Misses 492 492 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a significant refactoring of the benchmark tests and their documentation to showcase codegen under different data layouts. The changes are extensive, renaming and adding many files to create separate benchmarks for static_size, dynamic_size, and dynamic_padding layouts. The documentation macros have been completely overhauled for better modularity and to support these new tabbed examples. While the changes are generally excellent, I've found a minor issue in the CSS and a potential improvement in the new macro definitions.
| .codegen-tabs details[open] :is(summary) { | ||
| .codegen-tabs details[open] > summary { | ||
| background-color: var(--code-block-background-color); | ||
| border-bottom-color: var(--target-border-color); |
There was a problem hiding this comment.
The use of :is(summary) here is unnecessary as summary is the only valid child of details that can be a summary. Using the child combinator > is more direct and slightly more performant. It also improves clarity by being more specific about the intended structure.
.codegen-tabs details[open] > summary {| macro_rules! tabs { | ||
| ( | ||
| name = $name:expr, | ||
| arity = $arity:literal, | ||
| $([ | ||
| $($open:ident)? | ||
| @index $n:literal | ||
| @title $title:literal | ||
| $(#[doc = $content:expr])* | ||
| ]),* | ||
| ) => { | ||
| concat!(" | ||
| <div class='codegen-tabs' style='--arity: ", $arity ,"'>", $(concat!(" | ||
| <details name='tab-", $name,"' style='--n: ", $n ,"'", $(stringify!($open),)*"> | ||
| <summary><h6>", $title, "</h6></summary> | ||
| <div> | ||
|
|
||
| ```ignore | ||
| ", | ||
| include_str!(concat!("../benches/", $name, ".x86-64")), | ||
| "``` | ||
| ", $($content, "\n",)* " | ||
| \ | ||
| </div> | ||
| </details> | ||
| <details name='tab-", | ||
| $name, | ||
| "' style='--n: 4'> | ||
| <summary> | ||
| <h6>Machine Code Analysis</h6> | ||
| </summary> | ||
| <div> | ||
|
|
||
| ### Replication | ||
| </details>"),)* | ||
| "</div>") | ||
| } | ||
| } |
There was a problem hiding this comment.
The logic for processing doc comments within the tabs! macro is a duplication of the logic in the docstring! macro. To improve maintainability and reduce code duplication, you could refactor tabs! to use docstring!. This would require a bit of adjustment to how the doc comments are passed and processed within the macro system, but would centralize the doc comment processing logic.
There was a problem hiding this comment.
Code Review
This pull request is a significant and well-executed refactoring of the code generation documentation. It introduces a more flexible and powerful macro-based system for generating documentation with tabbed examples for different memory layouts. This greatly improves the documentation's utility for understanding the relationship between type complexity and codegen complexity. The addition of new benchmark variants for static size, dynamic size, and dynamic padding is also a valuable improvement to the test suite's robustness. The changes are consistent and well-structured. I have one suggestion to improve the documentation further.
| /// ```plain | ||
| #[doc = include_str!(concat!("../benches/", $bench, ".x86-64.mca"))] | ||
| /// ``` |
There was a problem hiding this comment.
The previous version of the documentation included instructions on how to replicate the machine code analysis using cargo-asm. This was very useful for users who wanted to run the analysis themselves. This information seems to have been lost in the refactoring.
Consider adding it back to the "Machine Code Analysis" tab. The command should be updated to be more accurate, including the --target-cpu and --simplify flags, and the correct function name.
For example:
@index 4
@title "Machine Code Analysis"
/// ### Replication
///
/// You may replicate this analysis on your device with [`cargo-show-asm`] by running:
///
/// [`cargo-show-asm`]: https://github.com/pacak/cargo-show-asm
///
/// ```bash
#[doc = concat!("cargo asm --bench ", $bench, " --target-cpu x86-64 --simplify --mca bench_", $bench)]
/// ```
///
/// ### Results
///
/// ```plain
#[doc = include_str!(concat!("../benches/", $bench, ".x86-64.mca"))]
/// ```
/// ### Replication
///
/// You may replicate this analysis on your device with [`cargo-show-asm`] by running:
///
/// [`cargo-show-asm`]: https://github.com/pacak/cargo-show-asm
///
/// ```bash
#[doc = concat!("cargo asm --bench ", $bench, " --target-cpu x86-64 --simplify --mca bench_", $bench)]
/// ```
///
/// ### Results
///
/// ```plain
#[doc = include_str!(concat!("../benches/", $bench, ".x86-64.mca"))]
/// ```
There was a problem hiding this comment.
Code Review
This pull request refactors the code generation benchmark documentation within the zerocopy crate. The changes involve replacing the existing codegen_tabs! macro with a new, more flexible suite of macros (tabs!, codegen_example!, codegen_example_suite!, codegen_preamble!, and codegen_section!). This new macro system allows for the documentation of multiple benchmark variants (static size, dynamic size, and dynamic padding) using HTML tabs in rustdoc, providing a more organized and detailed view of code generation. Consequently, numerous benchmark definitions in src/lib.rs and src/macros.rs have been updated to utilize the new codegen_section! macro, and new benchmark files, along with their assembly and machine code analysis outputs, have been added for these variants. The rustdoc/style.css file was also updated to support the new tabbed layout. Review comments indicate issues with the new documentation macros, specifically that the tabs! macro incorrectly generates the open HTML attribute, contains a stray backslash in its output, and has a mismatch in how it expects the open argument from codegen_example_suite!. The reviewer suggests using helper arms in the tabs! macro to correctly handle the optional open attribute.
Note: Security Review did not run due to the size of the PR.
| macro_rules! tabs { | ||
| ( | ||
| name = $name:expr, | ||
| arity = $arity:literal, | ||
| $([ | ||
| $($open:ident)? | ||
| @index $n:literal | ||
| @title $title:literal | ||
| $(#[doc = $content:expr])* | ||
| ]),* | ||
| ) => { | ||
| concat!(" | ||
| <div class='codegen-tabs' style='--arity: ", $arity ,"'>", $(concat!(" | ||
| <details name='tab-", $name,"' style='--n: ", $n ,"'", $(stringify!($open),)*"> | ||
| <summary><h6>", $title, "</h6></summary> | ||
| <div> | ||
|
|
||
| ```ignore | ||
| ", | ||
| include_str!(concat!("../benches/", $name, ".x86-64")), | ||
| "``` | ||
| ", $($content, "\n",)* " | ||
| \ | ||
| </div> | ||
| </details> | ||
| <details name='tab-", | ||
| $name, | ||
| "' style='--n: 4'> | ||
| <summary> | ||
| <h6>Machine Code Analysis</h6> | ||
| </summary> | ||
| <div> | ||
|
|
||
| ### Replication | ||
| </details>"),)* | ||
| "</div>") | ||
| } | ||
| } | ||
|
|
||
| You may replicate this analysis on your device with [`cargo-show-asm`] by running: | ||
| /// Generates the HTML for a single benchmark example. | ||
| #[allow(unused)] | ||
| macro_rules! codegen_example { | ||
| (format = $format:expr, bench = $bench:expr) => { | ||
| tabs!( | ||
| name = $bench, | ||
| arity = 4, | ||
| [ | ||
| @index 1 | ||
| @title "Format" | ||
| /// ```ignore | ||
| #[doc = include_str!(concat!("../benches/formats/", $format, ".rs"))] | ||
| /// ``` | ||
| ], | ||
| [ | ||
| @index 2 | ||
| @title "Benchmark" | ||
| /// ```ignore | ||
| #[doc = include_str!(concat!("../benches/", $bench, ".rs"))] | ||
| /// ``` | ||
| ], | ||
| [ | ||
| open | ||
| @index 3 | ||
| @title "Assembly" | ||
| /// ```plain | ||
| #[doc = include_str!(concat!("../benches/", $bench, ".x86-64"))] | ||
| /// ``` | ||
| ], | ||
| [ | ||
| @index 4 | ||
| @title "Machine Code Analysis" | ||
| /// ```plain | ||
| #[doc = include_str!(concat!("../benches/", $bench, ".x86-64.mca"))] | ||
| /// ``` | ||
| ] | ||
| ) | ||
| } | ||
| } | ||
|
|
||
| [`cargo-show-asm`]: https://github.com/pacak/cargo-show-asm | ||
| /// Generate the HTML for a suite of benchmark examples. | ||
| #[allow(unused)] | ||
| macro_rules! codegen_example_suite { | ||
| ( | ||
| bench = $bench:expr, | ||
| format = $format:expr, | ||
| arity = $arity:literal, | ||
| $([ | ||
| $($open:ident)? | ||
| @index $index:literal | ||
| @title $title:literal | ||
| @variant $variant:literal | ||
| ]),* | ||
| ) => { | ||
| tabs!( | ||
| name = $bench, | ||
| arity = $arity, | ||
| $([ | ||
| $($open)* | ||
| @index $index | ||
| @title $title | ||
| #[doc = codegen_example!( | ||
| format = concat!($format, "_", $variant), | ||
| bench = concat!($bench, "_", $variant) | ||
| )] | ||
| ]),* | ||
| ) | ||
| } | ||
| } |
There was a problem hiding this comment.
There are a few related issues in the new documentation generation macros:
- In
tabs!(line 883), the$(stringify!($open),)*part generates an invalidopenattribute. It produces something like<details ... "open">instead of the correct boolean attribute<details ... open>. The repetition*and comma are also problematic. - In
tabs!(line 888), there's a stray backslash\inside a string literal that will be rendered in the HTML. This seems to be a typo and should be removed. - In
codegen_example_suite!(line 953),$($open)*is passed totabs!. This should be$($open)?to match the optionalidentpattern intabs!.
A common way to fix the conditional open attribute is to use helper arms on the tabs! macro.
jswrenn
force-pushed
the
G39e297d5b891f5115ef9607b090c5fbe95427d68
branch
from
6f24e9a to
efab483
Compare
jswrenn
force-pushed
the
G39e297d5b891f5115ef9607b090c5fbe95427d68
branch
2 times, most recently
from
89ab1c2 to
a9921b5
Compare
jswrenn
force-pushed
the
G04affc58395810ba04b941f14dfdc20563fa850b
branch
from
11a76fa to
57741d2
Compare
For `TryFromBytes` and `FromBytes` tests: - Alignment is now 4. - Minimum size is now 12. - Trailing padding may be dynamically present. For `transmute_ref!` and `try_transmute_ref!`: - Metadata fixup required. gherrit-pr-id: G04affc58395810ba04b941f14dfdc20563fa850b
This improves the robustness of our suite to different code paths, and illustrates in our documentation the relationship between type complexity and codegen complexity. gherrit-pr-id: G39e297d5b891f5115ef9607b090c5fbe95427d68
jswrenn
force-pushed
the
G39e297d5b891f5115ef9607b090c5fbe95427d68
branch
from
a9921b5 to
87f0c90
Compare
jswrenn
force-pushed
the
G04affc58395810ba04b941f14dfdc20563fa850b
branch
from
57741d2 to
5eafa06
Compare
3 participants
This improves the robustness of our suite to different code paths, and
illustrates in our documentation the relationship between type
complexity and codegen complexity.
Latest Update: v5 — Compare vs v4
📚 Full Patch History
Links show the diff between the row version and the column version.
⬇️ Download this PR
Branch
git fetch origin refs/heads/G39e297d5b891f5115ef9607b090c5fbe95427d68 && git checkout -b pr-G39e297d5b891f5115ef9607b090c5fbe95427d68 FETCH_HEADCheckout
git fetch origin refs/heads/G39e297d5b891f5115ef9607b090c5fbe95427d68 && git checkout FETCH_HEADCherry Pick
git fetch origin refs/heads/G39e297d5b891f5115ef9607b090c5fbe95427d68 && git cherry-pick FETCH_HEADPull
Stacked PRs enabled by GHerrit.