Skip to content

More doc fixes for Options<T>. #23795

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.

Sign up for GitHub

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

Closed
wants to merge 1 commit into from
Closed

More doc fixes for Options<T>. #23795

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 44 additions & 30 deletions src/libcore/option.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@

//! Optional values
//!
//! Type `Option` represents an optional value: every `Option`
//! Type `Option<T>` represents an optional value: every `Option<T>`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I really don't think these are necessary.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 Option to make clear the trait is meant and have a consistent wording?
steveklabnik: it should always be Option<T>

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 :)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

//! is either `Some` and contains a value, or `None`, and
//! does not. `Option` types are very common in Rust code, as
//! does not. `Option<T>` types are very common in Rust code, as
//! they have a number of uses:
//!
//! * Initial values
Expand Down Expand Up @@ -51,15 +51,15 @@
//! ```
//!
//
// FIXME: Show how `Option` is used in practice, with lots of methods
// FIXME: Show how `Option<T>` is used in practice, with lots of methods
//
//! # Options and pointers ("nullable" pointers)
//!
//! Rust's pointer types must always point to a valid location; there are
//! no "null" pointers. Instead, Rust has *optional* pointers, like
//! the optional owned box, `Option<Box<T>>`.
//!
//! The following example uses `Option` to create an optional box of
//! The following example uses `Option<T>` to create an optional box of
//! `i32`. Notice that in order to use the inner `i32` value first the
//! `check_optional` function needs to use pattern matching to
//! determine whether the box has a value (i.e. it is `Some(...)`) or
Expand All @@ -80,14 +80,14 @@
//! }
//! ```
//!
//! This usage of `Option` to create safe nullable pointers is so
//! This usage of `Option<T>` to create safe nullable pointers is so
//! common that Rust does special optimizations to make the
//! representation of `Option<Box<T>>` a single pointer. Optional pointers
//! in Rust are stored as efficiently as any other pointer type.
//!
//! # Examples
//!
//! Basic pattern matching on `Option`:
//! Basic pattern matching on `Option<T>`:
//!
//! ```
//! let msg = Some("howdy");
Expand All @@ -98,7 +98,7 @@
//! None => ()
//! }
//!
//! // Remove the contained string, destroying the Option
//! // Remove the contained string, destroying the `Option<T>`
//! let unwrapped_msg = match msg {
//! Some(m) => m,
//! None => "default message"
Expand Down Expand Up @@ -160,9 +160,9 @@ use slice;
// Note that this is not a lang item per se, but it has a hidden dependency on
// `Iterator`, which is one. The compiler assumes that the `next` method of
// `Iterator` is an enumeration with one type parameter and two variants,
// which basically means it must be `Option`.
// which basically means it must be `Option<T>`.

/// The `Option` type. See [the module level documentation](../index.html) for more.
/// The `Option<T>` type. See [the module level documentation](../index.html) for more.
#[derive(Clone, Copy, PartialEq, PartialOrd, Eq, Ord, Debug, Hash)]
#[stable(feature = "rust1", since = "1.0.0")]
pub enum Option<T> {
Expand All @@ -183,7 +183,7 @@ impl<T> Option<T> {
// Querying the contained values
/////////////////////////////////////////////////////////////////////////

/// Returns `true` if the option is a `Some` value
/// Returns `true` if the `Option<T>` is a `Some(v)` value.
///
/// # Examples
///
Expand All @@ -203,7 +203,7 @@ impl<T> Option<T> {
}
}

/// Returns `true` if the option is a `None` value
/// Returns `true` if the `Option<T>` is a `None` value.
///
/// # Examples
///
Expand All @@ -224,13 +224,13 @@ impl<T> Option<T> {
// Adapter for working with references
/////////////////////////////////////////////////////////////////////////

/// Convert from `Option<T>` to `Option<&T>`
/// Convert from `Option<T>` to `Option<&T>`.
///
/// # Examples
///
/// Convert an `Option<String>` into an `Option<usize>`, preserving the original.
/// The `map` method takes the `self` argument by value, consuming the original,
/// so this technique uses `as_ref` to first take an `Option` to a reference
/// so this technique uses `as_ref` to first take an `Option<T>` to a reference
/// to the value inside the original.
///
/// ```
Expand All @@ -249,7 +249,7 @@ impl<T> Option<T> {
}
}

/// Convert from `Option<T>` to `Option<&mut T>`
/// Convert from `Option<T>` to `Option<&mut T>`.
///
/// # Examples
///
Expand All @@ -270,7 +270,7 @@ impl<T> Option<T> {
}
}

/// Convert from `Option<T>` to `&mut [T]` (without copying)
/// Convert from `Option<T>` to `&mut [T]` (without copying).
///
/// # Examples
///
Expand Down Expand Up @@ -304,7 +304,8 @@ impl<T> Option<T> {
// Getting to contained values
/////////////////////////////////////////////////////////////////////////

/// Unwraps an option, yielding the content of a `Some`
/// If the `Option<T>` is `Some(v)`, moves the value `v` out of the `Option<T>`.
/// Otherwise panics with the provided message `msg`.
///
/// # Panics
///
Expand Down Expand Up @@ -363,7 +364,8 @@ impl<T> Option<T> {
}
}

/// Returns the contained value or a default.
/// Moves the value `v` out of the `Option<T>` if the content of the
/// `Option<T>` is a `Some(v)` or returns the value of the argument `def`.
///
/// # Examples
///
Expand All @@ -380,7 +382,8 @@ impl<T> Option<T> {
}
}

/// Returns the contained value or computes it from a closure.
/// Moves the value `v` out of the `Option<T>` if the content of the
/// `Option<T>` is a `Some(v)` or computes it from a closure.
///
/// # Examples
///
Expand All @@ -402,7 +405,10 @@ impl<T> Option<T> {
// Transforming contained values
/////////////////////////////////////////////////////////////////////////

/// Maps an `Option<T>` to `Option<U>` by applying a function to a contained value
/// Transforms the `Option<T>` into a new `Option<U>`.
/// If the `Option<T>` is `None` then `f` is not invoked and `None` is returned.
/// Otherwise the result `u` of evaluating `f(v)` is returned as a `Some(u)`
/// where `v` is the value of the content `Some(v)` on the `Option<T>`.
///
/// # Examples
///
Expand All @@ -422,7 +428,10 @@ impl<T> Option<T> {
}
}

/// Applies a function to the contained value or returns a default.
/// Transforms the `Option<T>` into a new `Option<U>`.
/// If the `Option<T>` is `None` then `f` is not invoked and the `def` value
/// is returned. Otherwise the result of evaluating `f(v)` is returned where
/// `v` is the value of the content `Some(v)` on the `Option<T>`.
///
/// # Examples
///
Expand All @@ -442,7 +451,10 @@ impl<T> Option<T> {
}
}

/// Applies a function to the contained value or computes a default.
/// Transforms the `Option<T>` into a value of of type `U`.
/// If the `Option<T>` is `None` then the result of evaluating `def()` is returned.
/// Otherwise the result of evaluating `f(v)` is returned where `v` is the
/// value of the content `Some(v)` on the `Option<T>`.
///
/// # Examples
///
Expand Down Expand Up @@ -602,8 +614,8 @@ impl<T> Option<T> {
}
}

/// Returns `None` if the option is `None`, otherwise calls `f` with the
/// wrapped value and returns the result.
/// Returns `None` if the `Option<T>` is `None`, otherwise calls `f` with the
/// wrapped value `v` of the `Some(v)` and returns the result.
///
/// Some languages call this operation flatmap.
///
Expand All @@ -627,7 +639,8 @@ impl<T> Option<T> {
}
}

/// Returns the option if it contains a value, otherwise returns `optb`.
/// Returns the `Option<T>` if it contains a `Some(v)` value, otherwise
/// returns the argument value `optb`.
///
/// # Examples
///
Expand Down Expand Up @@ -657,8 +670,8 @@ impl<T> Option<T> {
}
}

/// Returns the option if it contains a value, otherwise calls `f` and
/// returns the result.
/// Returns the `Option<T>` if it contains a `Some(v)` value, otherwise calls
/// `f` and returns the result.
///
/// # Examples
///
Expand All @@ -683,17 +696,18 @@ impl<T> Option<T> {
// Misc
/////////////////////////////////////////////////////////////////////////

/// Takes the value out of the option, leaving a `None` in its place.
/// Returns the current `Option<T>` object and replaces its memory location
/// with `None`.
///
/// # Examples
///
/// ```
/// let mut x = Some(2);
/// x.take();
/// assert_eq!(x.take(), Some(2));
/// assert_eq!(x, None);
///
/// let mut x: Option<u32> = None;
/// x.take();
/// assert_eq!(x.take(), None);
/// assert_eq!(x, None);
/// ```
#[inline]
Expand Down Expand Up @@ -892,7 +906,7 @@ impl<A> ExactSizeIterator for IntoIter<A> {}
impl<A, V: FromIterator<A>> FromIterator<Option<A>> for Option<V> {
/// Takes each element in the `Iterator`: if it is `None`, no further
/// elements are taken, and the `None` is returned. Should no `None` occur, a
/// container with the values of each `Option` is returned.
/// container with the values of each `Option<T>` is returned.
///
/// Here is an example which increments every integer in a vector,
/// checking for overflow:
Expand Down