More doc fixes for Options<T>. #23795
Conversation
|
Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @nikomatsakis (or someone else) soon. If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. The way Github handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes. Please see CONTRIBUTING.md for more information. |
| @@ -10,9 +10,9 @@ | |||
|
|
|||
| //! Optional values | |||
| //! | |||
| //! Type `Option` represents an optional value: every `Option` | |||
| //! Type `Option<T>` represents an optional value: every `Option<T>` | |||
There was a problem hiding this comment.
I really don't think these are necessary.
There was a problem hiding this comment.
I asked @steveklabnik about this on IRC and he was in favor of adding them everywhere. Quoting from the IRC conversation at https://botbot.me/mozilla/rust/2015-03-27/?msg=35229748&page=24:
jviereck: The current docs use "option" and "Option" and "Option" when the type is relevant. Maybe all of the options should be renamed to
Optionto make clear the trait is meant and have a consistent wording?
steveklabnik: it should always beOption<T>
There was a problem hiding this comment.
Is that going to be the new convention? It seems way too redundant and a bit distracting. Is HashMap::contains_key's documentation going to become
Returns true if the `HashMap<K, V, S>` contains a value for the specified key.
My preference is to use a lowercase non-Rust-type word when the meaning is obvious, which it is when we're talking about methods on a type, but I guess this needs some kind of guidelines RFC. At the very least, I don't think we need to use the type parameter everywhere.
There was a problem hiding this comment.
As I've just entered the Rust community I don't think I have (and don't intend to have) a strong vote here.
@apasel422, @steveklabnik, please let me just know what you both agree on and I am more than happy to adjust the RFC whatever you come up with :)
There was a problem hiding this comment.
I thought I included this in https://github.com/rust-lang/rfcs/blob/master/text/0505-api-comment-conventions.md, but apparently did not.
We've been preferring the type params always in the single or double param case, and doing it on a case-by-case basis with more than three. Option<T> should use it.
|
closing since we did #23862 |
|
@steveklabnik AFAIKT the changes in #23862 and here are unrelated? Therefore I don't see why this PR is closed with reference to #23862. Can you please have a second look at it? Thanks! And sorry in case I caused confusion by cross referencing issues though they are not really related content wise :/ |
Replaces a few option within Option and improves docs for transformation.