clarify behavior of __ptr32/__ptr64 example #5860
Conversation
|
@jdpatdiscord : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change. |
prmerger-automator
bot
added
Change sent to author
cpp-lang/subsvc
visual-cpp/svc
labels
|
Learn Build status updates of commit 5175ad6: ✅ Validation status: passed
For more details, please refer to the build report. |
|
Can you review the proposed changes? Important: When the changes are ready for publication, adding a #label:"aq-pr-triaged" |
prmerger-automator
bot
added
the
aq-pr-triaged
There was a problem hiding this comment.
Pull request overview
This PR clarifies the behavior of the __ptr32 and __ptr64 example code by explaining that the example crashes when compiled for 64-bit but may not crash when compiled for 32-bit, addressing potential confusion about the expected output shown in the documentation.
Key changes:
- Added clarification that the example code crashes on 64-bit compilation due to pointer truncation
- Explained why the code does not necessarily crash on 32-bit compilation
docs/cpp/ptr32-ptr64.md
Outdated
| ## Example | ||
|
|
||
| The following example shows how to declare and allocate pointers with the **`__ptr32`** and **`__ptr64`** keywords. | ||
| The following example shows how to declare and allocate pointers with the **`__ptr32`** and **`__ptr64`** keywords. This code will crash when compiled for 64-bit due to the pointer from `malloc` being truncated to 32-bit. Since 32-bit pointers can be represented in 64-bit, when compiled for 32-bit this code does not necessarily crash. |
There was a problem hiding this comment.
The phrase "This code will crash" uses future tense ("will"). According to the Microsoft Writing Style Guide, use present tense verbs instead of future tense. Consider: "This code crashes when compiled for 64-bit..."
|
Any thoughts on what to keep from the Copilot suggestions? |
Updated to address Copilot suggestions.
|
@jdpatdiscord , I took a shot at it and updated the PR. See what you think. |
|
Learn Build status updates of commit 5b6b51b: ✅ Validation status: passed
For more details, please refer to the build report. |
|
Closing/reopening to refresh the CLA status |
|
Learn Build status updates of commit 5b6b51b: ✅ Validation status: passed
For more details, please refer to the build report. |
|
@jdpatdiscord Thank you for your contribution. Would you take a moment to sign the Contributor License Agreement (CLA)? We won't be able to merge this PR without it. #label:"aq-pr-triaged" |
I have no problems with the changes given that it's possible to allocate at low address ranges on a 64-bit process between various linker flags and VirtualAlloc behavior. My changes I wanted to keep short to just avoid problems and convey the idea as short as possible. |
|
@microsoft-github-policy-service agree |
TylerMSFT
left a comment
TylerMSFT
left a comment
There was a problem hiding this comment.
Thank you @jdpatdiscord for your clarification in this article.
|
#sign-off |
3 participants
Without this clarification, it implies that you will always get the example output. I see no reason to change the actual example code other than to just make clear what the behavior of it will be under different bitness.