-
Notifications
You must be signed in to change notification settings - Fork 520
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Fix various grammatical errors around ?Sized #992
Conversation
* Section 10.2 contains two sentences which are not sentences (I.E., they do not contain verbs). Patch makes the sentences grammatical and less ambugious, also links on the phrase ?Sized to the stdlib doc for Sized which is the clearest explanation of what ?Sized does I can find. * Section 10.6 contains the text '? is only used to declare that the Sized trait may not be implemented for a type parameter or associated type'. 'May not' makes it sound as if it is prohibited to implement the Sized trait, whereas in fact the text means that the type may at its option fail to implement the sized trait. Patch clarifies.
Addresses #987 |
A note: The best explanation of ?Sized I've found is attached to Sized, in the stdlib. In the current version of this patch, when I mention ?Sized I link to "?Sized" in the reference. This means the current status of Sized/?Sized documentation is:
This all feels real backward. Getting the defaults wrong/misleading in the reference is especially concerning because this (defaults) is the exact material which is relevant for the reference rather than the stdlib. This PR currently constitutes a minimal change to make the text readable, but in my opinion a better way to structure this overall would be:
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Review addresses the PR specifically.
I don't see any problem with the prose. I agree it is an improvement over what is currently there. I do have a few changes, but they are just one (small but crucial) factual inconsistency and three grammar/style things.
@@ -11,10 +11,10 @@ types">DSTs</abbr>. Such types can only be used in certain cases: | |||
* Pointers to slices also store the number of elements of the slice. | |||
* Pointers to trait objects also store a pointer to a vtable. | |||
* <abbr title="dynamically sized types">DSTs</abbr> can be provided as | |||
type arguments when a bound of `?Sized`. By default any type parameter | |||
has a `Sized` bound. | |||
type arguments when the type parameter has the special lifetime bound [`?Sized`](trait-bounds.html#sized) specified. (In other words by default any type parameter on a non-trait item |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
type arguments when the type parameter has the special lifetime bound [`?Sized`](trait-bounds.html#sized) specified. (In other words by default any type parameter on a non-trait item | |
type arguments when the type parameter has the special trait bound [`?Sized`](trait-bounds.html#sized) specified. (In other words by default any type parameter on a non-trait item |
@@ -11,10 +11,10 @@ types">DSTs</abbr>. Such types can only be used in certain cases: | |||
* Pointers to slices also store the number of elements of the slice. | |||
* Pointers to trait objects also store a pointer to a vtable. | |||
* <abbr title="dynamically sized types">DSTs</abbr> can be provided as | |||
type arguments when a bound of `?Sized`. By default any type parameter | |||
has a `Sized` bound. | |||
type arguments when the type parameter has the special lifetime bound [`?Sized`](trait-bounds.html#sized) specified. (In other words by default any type parameter on a non-trait item |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The parenthesis are not needed. The "In other words" already guards the sentence enough.
There's also needed commas after the "In other words" and "by default".
Also, as per the style guide, links in prose should just be the text and then have link refs at the bottom in alphabetical (well, UTF-8 codepoint) order.
`?` is only used to declare that the [`Sized`] trait may not be | ||
implemented for a type parameter or associated type. `?Sized` may | ||
`?` is only used to declare that the [`Sized`] trait may be | ||
unimplemented for a type parameter or associated type. `?Sized` may |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it might be better to say "is not required" instead of "may be unimplemented". Maybe add a parenthetical "(Type parameters and associated types have an implicit Sized
bound.)" after this sentence.
I am not completely certain about this text. I think my text is better (because the existing text is not valid English) but my text is definitely more ungainly. (I would love to find an excuse to remove the words "a non-trait item" in the first bullet point.) I also do not know for a fact that my replacement text is correct— it is my best guess from looking at the other documentation (in particular Sized in the stdlib). I am new at Rust and have yet to learn traits.
[EDIT: Removed note about ?sized link]