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
| ## 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..."
| ## 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.
According to the Microsoft Writing Style Guide, break up long sentences for better readability. This sentence contains multiple independent clauses. Consider splitting into separate sentences:
"This code crashes when compiled for 64-bit due to the pointer from malloc being truncated to 32-bit. When compiled for 32-bit, this code does not necessarily crash because 32-bit pointers can be represented in 64-bit."
| ## 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 phrasing "when compiled for 32-bit this code does not necessarily crash" is ambiguous. The statement "32-bit pointers can be represented in 64-bit" appears to be explaining the wrong scenario - it should explain why 64-bit pointers can fit in 32-bit address space on 32-bit systems (they can't exceed 32-bit addresses). Consider clarifying the technical explanation:
"When compiled for 32-bit, this code does not crash because the __ptr64 pointer is truncated to 32-bit, which is sufficient for the 32-bit address space."
| 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. | |
| 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 because the pointer from `malloc` is truncated to 32 bits. When compiled for 32-bit, this code does not crash because the `__ptr64` pointer is truncated to 32 bits, which is sufficient for the 32-bit address space. |
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.