[macros] Clarify size/align behavior of try macros

[joshlf]

Clarify that, while try_transmute_{ref,mut}! check referent validity
at runtime, they enforce size and alignment compatibility at compile
time.

Release 0.8.38.

---

• 👉 [macros] Clarify size/align behavior of try macros #2975

Latest Update: v2 — Compare vs v1

📚 Full Patch History

Links show the diff between the row version and the column version.

Version	v1	Base
v2	vs v1	vs Base
v1		vs Base

⬇️ Download this PR

Branch

git fetch origin refs/heads/G2712a29a4b58bdb5d76d4b15763a15f8e8824ae0 && git checkout -b pr-G2712a29a4b58bdb5d76d4b15763a15f8e8824ae0 FETCH_HEAD

Checkout

git fetch origin refs/heads/G2712a29a4b58bdb5d76d4b15763a15f8e8824ae0 && git checkout FETCH_HEAD

Cherry Pick

git fetch origin refs/heads/G2712a29a4b58bdb5d76d4b15763a15f8e8824ae0 && git cherry-pick FETCH_HEAD

Pull

git pull origin refs/heads/G2712a29a4b58bdb5d76d4b15763a15f8e8824ae0

Stacked PRs enabled by GHerrit.

[gemini-code-assist]

Summary of Changes

Hello @joshlf, I'm Gemini Code Assist¹! 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 enhances the clarity of the documentation for the try_transmute_ref! and try_transmute_mut! macros. The updates precisely differentiate between the runtime validation of referent values and the compile-time enforcement of size and alignment constraints. Additionally, it directs users to the TryFromBytes trait for scenarios requiring fallible conversions based on size and alignment, thereby improving user understanding and guiding them to appropriate APIs.

Highlights

• Documentation Clarification for try_transmute_ref!: Added a note to the try_transmute_ref! macro documentation to explicitly state that referent value validity is checked at runtime, while size and alignment compatibility are enforced at compile time.
• Documentation Clarification for try_transmute_mut!: Added a similar note to the try_transmute_mut! macro documentation, clarifying the distinction between runtime value checks and compile-time size/alignment checks.
• Reference to TryFromBytes: Included a reference to the TryFromBytes trait in the documentation for both try_transmute_ref! and try_transmute_mut! macros, guiding users to methods for conversions that are fallible with respect to size and alignment.

🧠 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

• src/macros.rs
  • Updated the documentation for try_transmute_ref! to clarify that referent validity is checked at runtime, while size and alignment are checked at compile time.
  • Added a link to crate::TryFromBytes within the try_transmute_ref! documentation.
  • Updated the documentation for try_transmute_mut! to clarify that referent validity is checked at runtime, while size and alignment are checked at compile time.
  • Added a link to crate::TryFromBytes within the try_transmute_mut! documentation.

Activity

• No human activity (comments, reviews, or progress updates) has been recorded for this pull request yet.

Using Gemini Code Assist

The 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 /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

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 .gemini/ folder in the base of the repository. Detailed instructions can be found here.

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

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request clarifies the behavior of the try_transmute_ref! and try_transmute_mut! macros in their documentation. The added notes correctly state that size and alignment compatibility are checked at compile time, while the validity of the referent's value is checked at runtime. This is an important distinction that improves the clarity of the documentation for users of these macros. The changes are accurate and well-implemented. I have no further suggestions.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.02%. Comparing base (42ff03b) to head (03b5166).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2975   +/-   ##
=======================================
  Coverage   92.02%   92.02%           
=======================================
  Files          19       19           
  Lines        6029     6029           
=======================================
  Hits         5548     5548           
  Misses        481      481           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.