Rephrase conversion methods' documentation to accommodate DSTs #1269
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
joshlf
reviewed
May 15, 2024
joshlf
requested changes
May 15, 2024
src/lib.rs
Outdated
| /// length, alignment, or overflow checks fail, it returns `Err`. | ||
| /// This method attempts to return a reference to the prefix of `bytes` | ||
| /// reinterpreted as a `Self` with `count` trailing elements, and reference | ||
| /// to the preceeding bytes. If there are insufficient bytes, or if `bytes` |
There was a problem hiding this comment.
Suggested change
| /// to the preceeding bytes. If there are insufficient bytes, or if `bytes` | |
| /// to the remaining bytes. If there are insufficient bytes, or if `bytes` |
Or something else, but "preceding" only works if this were a suffix cast.
src/lib.rs
Outdated
| /// length, alignment, or overflow checks fail, it returns `Err`. | ||
| /// This method attempts to return a reference to the suffix of `bytes` | ||
| /// reinterpreted as a `Self` with `count` trailing elements, and reference | ||
| /// to the preceeding bytes. If there are insufficient bytes, or if that |
There was a problem hiding this comment.
Suggested change
| /// to the preceeding bytes. If there are insufficient bytes, or if that | |
| /// to the preceding bytes. If there are insufficient bytes, or if that |
joshlf
requested changes
May 15, 2024
src/lib.rs
Outdated
| /// If the bytes of `candidate` are a valid instance of `Self`, reads those | ||
| /// bytes as `Self`. If `candidate.len() < size_of::<Self>()` or the bytes | ||
| /// are not a valid instance of `Self`, this returns `Err`. | ||
| /// If `candidate.len() < size_of::<Self>()` or the bytes are not a valid |
There was a problem hiding this comment.
Suggested change
| /// If `candidate.len() < size_of::<Self>()` or the bytes are not a valid | |
| /// If `candidate.len() != size_of::<Self>()` or the bytes are not a valid |
src/lib.rs
Outdated
Comment on lines
2279
to
2281
| /// This method attempts to return a reference to `bytes` interpreted as a | ||
| /// `Self`. If there are insufficient or excess bytes, or if `bytes` is not | ||
| /// aligned to `Self`'s alignment requirement, this returns `Err`. |
There was a problem hiding this comment.
Here I think the old wording - "valid length for Self" (although I'd say size instead of length) - makes more sense. "Insufficient or excess" implies that there's one correct size, but that's not true - there could be many correct sizes.
There was a problem hiding this comment.
How could there be many correct sizes? Isn't this backed by a try_cast_into_no_leftover?
There was a problem hiding this comment.
Ah, I see your point. There's only one correct size per DST length though.
src/lib.rs
Outdated
Comment on lines
2487
to
2489
| /// This method attempts to return a reference to `bytes` interpreted as a | ||
| /// `Self`. If there are insufficient or excess bytes, or if `bytes` is not | ||
| /// aligned to `Self`'s alignment requirement, this returns `Err`. |
jswrenn
commented
May 15, 2024
src/lib.rs
Outdated
| /// bytes. If `bytes.len() < size_of::<Self>()` or `bytes` is not aligned to | ||
| /// `align_of::<Self>()`, this returns `Err`. | ||
| /// This method computes the largest possible size of `Self` that can fit in | ||
| /// the leading bytes of `candidate`, then attempts to return both a |
There was a problem hiding this comment.
Whoops, this shouldn't be "bytes of candidate".
"bytes of bytes" is awkward, so perhaps I'll rename bytes to source.
joshlf
requested changes
May 16, 2024
src/lib.rs
Outdated
Comment on lines
2704
to
2705
| /// `Self` with `count` trailing elements. If the length of `source` is not | ||
| /// a valid size of `Self`, or if `source` is not appropriately aligned, |
There was a problem hiding this comment.
"Valid size of Self" isn't the right condition when an explicit count is given.
src/ref.rs
Outdated
Comment on lines
441
to
442
| /// the remaining bytes. If the length of `source` is not a valid size of | ||
| /// `T`, or if `source` is not appropriately aligned, this returns `Err`. |
There was a problem hiding this comment.
"Valid size of T" isn't the right condition when an explicit count is given.
src/ref.rs
Outdated
Comment on lines
648
to
649
| /// the remaining bytes. If the length of `source` is not a valid size of | ||
| /// `T`, this returns `Err`. |
There was a problem hiding this comment.
"Valid size of T" isn't the right condition when an explicit count is given.
src/ref.rs
Outdated
| /// This method attempts to return a `Ref` to the suffix of `source` | ||
| /// interpreted as a `T` with `count` trailing elements, and a reference to | ||
| /// the preceding bytes. If there are insufficient bytes, or if that suffix | ||
| /// of `source` is not appropriately aligned, this returns `Err`. |
src/ref.rs
Outdated
| /// This method attempts to return a `Ref` to the prefix of `source` | ||
| /// interpreted as a `T` with `count` trailing elements, and a reference to | ||
| /// the remaining bytes. If there are insufficient bytes, or if `source` is | ||
| /// not appropriately aligned, this returns `Err`. |
joshlf
approved these changes
May 16, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This entails removing reference to both
size_ofandalign_of, which cannot be invoked on slice DSTs.