Fix overlength lines in core::pin.

Author: steffahn

library/core/src/pin.rs

@@ -14,13 +14,15 @@
 //! for more details.
 //!
 //! By default, all types in Rust are movable. Rust allows passing all types by-value,
-//! and common smart-pointer types such as <code>[Box]\<T></code> and <code>[&mut] T</code> allow replacing and
-//! moving the values they contain: you can move out of a <code>[Box]\<T></code>, or you can use [`mem::swap`].
-//! <code>[Pin]\<P></code> wraps a pointer type `P`, so <code>[Pin]<[Box]\<T>></code> functions much like a regular
-//! <code>[Box]\<T></code>: when a <code>[Pin]<[Box]\<T>></code> gets dropped, so do its contents, and the memory gets
-//! deallocated. Similarly, <code>[Pin]<[&mut] T></code> is a lot like <code>[&mut] T</code>. However, <code>[Pin]\<P></code> does
-//! not let clients actually obtain a <code>[Box]\<T></code> or <code>[&mut] T</code> to pinned data, which implies that you
-//! cannot use operations such as [`mem::swap`]:
+//! and common smart-pointer types such as <code>[Box]\<T></code> and <code>[&mut] T</code> allow
+//! replacing and moving the values they contain: you can move out of a <code>[Box]\<T></code>,
+//! or you can use [`mem::swap`]. <code>[Pin]\<P></code> wraps a pointer type `P`, so
+//! <code>[Pin]<[Box]\<T>></code> functions much like a regular <code>[Box]\<T></code>:
+//! when a <code>[Pin]<[Box]\<T>></code> gets dropped, so do its contents, and the memory gets
+//! deallocated. Similarly, <code>[Pin]<[&mut] T></code> is a lot like <code>[&mut] T</code>.
+//! However, <code>[Pin]\<P></code> does not let clients actually obtain a <code>[Box]\<T></code>
+//! or <code>[&mut] T</code> to pinned data, which implies that you cannot use operations such
+//! as [`mem::swap`]:
 //!
 //! ```
 //! use std::pin::Pin;
@@ -32,17 +34,17 @@
 //! }
 //! ```
 //!
-//! It is worth reiterating that <code>[Pin]\<P></code> does *not* change the fact that a Rust compiler
-//! considers all types movable. [`mem::swap`] remains callable for any `T`. Instead, <code>[Pin]\<P></code>
-//! prevents certain *values* (pointed to by pointers wrapped in <code>[Pin]\<P></code>) from being
-//! moved by making it impossible to call methods that require <code>[&mut] T</code> on them
-//! (like [`mem::swap`]).
+//! It is worth reiterating that <code>[Pin]\<P></code> does *not* change the fact that a Rust
+//! compiler considers all types movable. [`mem::swap`] remains callable for any `T`. Instead,
+//! <code>[Pin]\<P></code> prevents certain *values* (pointed to by pointers wrapped in
+//! <code>[Pin]\<P></code>) from being moved by making it impossible to call methods that require
+//! <code>[&mut] T</code> on them (like [`mem::swap`]).
 //!
 //! <code>[Pin]\<P></code> can be used to wrap any pointer type `P`, and as such it interacts with
-//! [`Deref`] and [`DerefMut`]. A <code>[Pin]\<P></code> where <code>P: [Deref]</code> should be considered
-//! as a "`P`-style pointer" to a pinned <code>P::[Target]</code> – so, a <code>[Pin]<[Box]\<T>></code> is
-//! an owned pointer to a pinned `T`, and a <code>[Pin]<[Rc]\<T>></code> is a reference-counted
-//! pointer to a pinned `T`.
+//! [`Deref`] and [`DerefMut`]. A <code>[Pin]\<P></code> where <code>P: [Deref]</code> should be
+//! considered as a "`P`-style pointer" to a pinned <code>P::[Target]</code> – so, a
+//! <code>[Pin]<[Box]\<T>></code> is an owned pointer to a pinned `T`, and a
+//! <code>[Pin]<[Rc]\<T>></code> is a reference-counted pointer to a pinned `T`.
 //! For correctness, <code>[Pin]\<P></code> relies on the implementations of [`Deref`] and
 //! [`DerefMut`] not to move out of their `self` parameter, and only ever to
 //! return a pointer to pinned data when they are called on a pinned pointer.
@@ -54,13 +56,13 @@
 //! [`bool`], [`i32`], and references) as well as types consisting solely of these
 //! types. Types that do not care about pinning implement the [`Unpin`]
 //! auto-trait, which cancels the effect of <code>[Pin]\<P></code>. For <code>T: [Unpin]</code>,
-//! <code>[Pin]<[Box]\<T>></code> and <code>[Box]\<T></code> function identically, as do <code>[Pin]<[&mut] T></code> and
-//! <code>[&mut] T</code>.
+//! <code>[Pin]<[Box]\<T>></code> and <code>[Box]\<T></code> function identically, as do
+//! <code>[Pin]<[&mut] T></code> and <code>[&mut] T</code>.
 //!
-//! Note that pinning and [`Unpin`] only affect the pointed-to type <code>P::[Target]</code>, not the pointer
-//! type `P` itself that got wrapped in <code>[Pin]\<P></code>. For example, whether or not <code>[Box]\<T></code> is
-//! [`Unpin`] has no effect on the behavior of <code>[Pin]<[Box]\<T>></code> (here, `T` is the
-//! pointed-to type).
+//! Note that pinning and [`Unpin`] only affect the pointed-to type <code>P::[Target]</code>,
+//! not the pointer type `P` itself that got wrapped in <code>[Pin]\<P></code>. For example,
+//! whether or not <code>[Box]\<T></code> is [`Unpin`] has no effect on the behavior of
+//! <code>[Pin]<[Box]\<T>></code> (here, `T` is the pointed-to type).
 //!
 //! # Example: self-referential struct
 //!
@@ -149,8 +151,8 @@
 //! when [`drop`] is called*.  Only once [`drop`] returns or panics, the memory may be reused.
 //!
 //! Memory can be "invalidated" by deallocation, but also by
-//! replacing a <code>[Some]\(v)</code> by [`None`], or calling [`Vec::set_len`] to "kill" some elements
-//! off of a vector. It can be repurposed by using [`ptr::write`] to overwrite it without
+//! replacing a <code>[Some]\(v)</code> by [`None`], or calling [`Vec::set_len`] to "kill" some
+//! elements off of a vector. It can be repurposed by using [`ptr::write`] to overwrite it without
 //! calling the destructor first. None of this is allowed for pinned data without calling [`drop`].
 //!
 //! This is exactly the kind of guarantee that the intrusive linked list from the previous
@@ -172,8 +174,8 @@
 //! This can never cause a problem in safe code because implementing a type that
 //! relies on pinning requires unsafe code, but be aware that deciding to make
 //! use of pinning in your type (for example by implementing some operation on
-//! <code>[Pin]<[&]Self></code> or <code>[Pin]<[&mut] Self></code>) has consequences for your [`Drop`][Drop]
-//! implementation as well: if an element of your type could have been pinned,
+//! <code>[Pin]<[&]Self></code> or <code>[Pin]<[&mut] Self></code>) has consequences for your
+//! [`Drop`][Drop]implementation as well: if an element of your type could have been pinned,
 //! you must treat [`Drop`][Drop] as implicitly taking <code>[Pin]<[&mut] Self></code>.
 //!
 //! For example, you could implement [`Drop`][Drop] as follows:
@@ -206,16 +208,16 @@
 //! When working with pinned structs, the question arises how one can access the
 //! fields of that struct in a method that takes just <code>[Pin]<[&mut] Struct></code>.
 //! The usual approach is to write helper methods (so called *projections*)
-//! that turn <code>[Pin]<[&mut] Struct></code> into a reference to the field, but what
-//! type should that reference have? Is it <code>[Pin]<[&mut] Field></code> or <code>[&mut] Field</code>?
+//! that turn <code>[Pin]<[&mut] Struct></code> into a reference to the field, but what type should
+//! that reference have? Is it <code>[Pin]<[&mut] Field></code> or <code>[&mut] Field</code>?
 //! The same question arises with the fields of an `enum`, and also when considering
-//! container/wrapper types such as <code>[Vec]\<T></code>, <code>[Box]\<T></code>, or <code>[RefCell]\<T></code>.
-//! (This question applies to both mutable and shared references, we just
-//! use the more common case of mutable references here for illustration.)
+//! container/wrapper types such as <code>[Vec]\<T></code>, <code>[Box]\<T></code>,
+//! or <code>[RefCell]\<T></code>. (This question applies to both mutable and shared references,
+//! we just use the more common case of mutable references here for illustration.)
 //!
-//! It turns out that it is actually up to the author of the data structure
-//! to decide whether the pinned projection for a particular field turns
-//! <code>[Pin]<[&mut] Struct></code> into <code>[Pin]<[&mut] Field></code> or <code>[&mut] Field</code>. There are some
+//! It turns out that it is actually up to the author of the data structure to decide whether
+//! the pinned projection for a particular field turns <code>[Pin]<[&mut] Struct></code>
+//! into <code>[Pin]<[&mut] Field></code> or <code>[&mut] Field</code>. There are some
 //! constraints though, and the most important constraint is *consistency*:
 //! every field can be *either* projected to a pinned reference, *or* have
 //! pinning removed as part of the projection. If both are done for the same field,
@@ -283,19 +285,20 @@
 //!     the principle that you only have to worry about any of this if you use [`unsafe`].)
 //! 2.  The destructor of the struct must not move structural fields out of its argument. This
 //!     is the exact point that was raised in the [previous section][drop-impl]: [`drop`] takes
-//!     <code>[&mut] self</code>, but the struct (and hence its fields) might have been pinned before.
-//!     You have to guarantee that you do not move a field inside your [`Drop`][Drop] implementation.
-//!     In particular, as explained previously, this means that your struct must *not*
-//!     be `#[repr(packed)]`.
+//!     <code>[&mut] self</code>, but the struct (and hence its fields) might have been pinned
+//!     before. You have to guarantee that you do not move a field inside your [`Drop`][Drop]
+//!     implementation. In particular, as explained previously, this means that your struct
+//!     must *not* be `#[repr(packed)]`.
 //!     See that section for how to write [`drop`] in a way that the compiler can help you
 //!     not accidentally break pinning.
 //! 3.  You must make sure that you uphold the [`Drop` guarantee][drop-guarantee]:
 //!     once your struct is pinned, the memory that contains the
 //!     content is not overwritten or deallocated without calling the content's destructors.
-//!     This can be tricky, as witnessed by <code>[VecDeque]\<T></code>: the destructor of <code>[VecDeque]\<T></code>
-//!     can fail to call [`drop`] on all elements if one of the destructors panics. This violates
-//!     the [`Drop`][Drop] guarantee, because it can lead to elements being deallocated without
-//!     their destructor being called. (<code>[VecDeque]\<T></code> has no pinning projections, so this
+//!     This can be tricky, as witnessed by <code>[VecDeque]\<T></code>: the destructor of
+//!     <code>[VecDeque]\<T></code> can fail to call [`drop`] on all elements if one of the
+//!     destructors panics. This violates the [`Drop`][Drop] guarantee, because it can lead to
+//!     elements being deallocated without their destructor being called.
+//!     (<code>[VecDeque]\<T></code> has no pinning projections, so this
 //!     does not cause unsoundness.)
 //! 4.  You must not offer any other operations that could lead to data being moved out of
 //!     the structural fields when your type is pinned. For example, if the struct contains an
@@ -304,8 +307,9 @@
 //!     that operation can be used to move a `T` out of a pinned `Struct<T>` – which means
 //!     pinning cannot be structural for the field holding this data.
 //!
-//!     For a more complex example of moving data out of a pinned type, imagine if <code>[RefCell]\<T></code>
-//!     had a method <code>fn get_pin_mut(self: [Pin]<[&mut] Self>) -> [Pin]<[&mut] T></code>.
+//!     For a more complex example of moving data out of a pinned type,
+//!     imagine if <code>[RefCell]\<T></code> had a method
+//!     <code>fn get_pin_mut(self: [Pin]<[&mut] Self>) -> [Pin]<[&mut] T></code>.
 //!     Then we could do the following:
 //!     ```compile_fail
 //!     fn exploit_ref_cell<T>(rc: Pin<&mut RefCell<T>>) {
@@ -315,31 +319,33 @@
 //!         let content = &mut *b; // And here we have `&mut T` to the same data.
 //!     }
 //!     ```
-//!     This is catastrophic, it means we can first pin the content of the <code>[RefCell]\<T></code>
-//!     (using <code>[RefCell]::get_pin_mut</code>) and then move that content using the mutable
-//!     reference we got later.
+//!     This is catastrophic, it means we can first pin the content of the
+//!     <code>[RefCell]\<T></code> (using <code>[RefCell]::get_pin_mut</code>) and then move that
+//!     content using the mutable reference we got later.
 //!
 //! ## Examples
 //!
-//! For a type like <code>[Vec]\<T></code>, both possibilities (structural pinning or not) make sense.
-//! A <code>[Vec]\<T></code> with structural pinning could have `get_pin`/`get_pin_mut` methods to get
-//! pinned references to elements. However, it could *not* allow calling
-//! [`pop`][Vec::pop] on a pinned <code>[Vec]\<T></code> because that would move the (structurally pinned)
-//! contents! Nor could it allow [`push`][Vec::push], which might reallocate and thus also move the
-//! contents.
+//! For a type like <code>[Vec]\<T></code>, both possibilities (structural pinning or not) make
+//! sense. A <code>[Vec]\<T></code> with structural pinning could have `get_pin`/`get_pin_mut`
+//! methods to get pinned references to elements. However, it could *not* allow calling
+//! [`pop`][Vec::pop] on a pinned <code>[Vec]\<T></code> because that would move the (structurally
+//! pinned) contents! Nor could it allow [`push`][Vec::push], which might reallocate and thus also
+//! move the contents.
 //!
-//! A <code>[Vec]\<T></code> without structural pinning could <code>impl\<T> [Unpin] for [Vec]\<T></code>, because the contents
-//! are never pinned and the <code>[Vec]\<T></code> itself is fine with being moved as well.
+//! A <code>[Vec]\<T></code> without structural pinning could
+//! <code>impl\<T> [Unpin] for [Vec]\<T></code>, because the contents are never pinned
+//! and the <code>[Vec]\<T></code> itself is fine with being moved as well.
 //! At that point pinning just has no effect on the vector at all.
 //!
 //! In the standard library, pointer types generally do not have structural pinning,
-//! and thus they do not offer pinning projections. This is why <code>[Box]\<T>: [Unpin]</code> holds for all `T`.
-//! It makes sense to do this for pointer types, because moving the <code>[Box]\<T></code>
-//! does not actually move the `T`: the <code>[Box]\<T></code> can be freely movable (aka [`Unpin`]) even if
-//! the `T` is not. In fact, even <code>[Pin]<[Box]\<T>></code> and <code>[Pin]<[&mut] T></code> are always
-//! [`Unpin`] themselves, for the same reason: their contents (the `T`) are pinned, but the
-//! pointers themselves can be moved without moving the pinned data. For both <code>[Box]\<T></code> and
-//! <code>[Pin]<[Box]\<T>></code>, whether the content is pinned is entirely independent of whether the
+//! and thus they do not offer pinning projections. This is why <code>[Box]\<T>: [Unpin]</code>
+//! holds for all `T`. It makes sense to do this for pointer types, because moving the
+//! <code>[Box]\<T></code> does not actually move the `T`: the <code>[Box]\<T></code> can be freely
+//! movable (aka [`Unpin`]) even if the `T` is not. In fact, even <code>[Pin]<[Box]\<T>></code> and
+//! <code>[Pin]<[&mut] T></code> are always [`Unpin`] themselves, for the same reason:
+//! their contents (the `T`) are pinned, but the pointers themselves can be moved without moving
+//! the pinned data. For both <code>[Box]\<T></code> and <code>[Pin]<[Box]\<T>></code>,
+//! whether the content is pinned is entirely independent of whether the
 //! pointer is pinned, meaning pinning is *not* structural.
 //!
 //! When implementing a [`Future`] combinator, you will usually need structural pinning