Skip to content

Commit 99c2f72

Browse files
Rollup merge of #36363 - GuillaumeGomez:add_urls, r=steveklabnik
Add urls r? @steveklabnik
2 parents d939cbe + e3153cf commit 99c2f72

File tree

4 files changed

+160
-89
lines changed

4 files changed

+160
-89
lines changed

src/libcore/clone.rs

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,14 @@
1414
//! assign them or pass them as arguments, the receiver will get a copy,
1515
//! leaving the original value in place. These types do not require
1616
//! allocation to copy and do not have finalizers (i.e. they do not
17-
//! contain owned boxes or implement `Drop`), so the compiler considers
17+
//! contain owned boxes or implement [`Drop`]), so the compiler considers
1818
//! them cheap and safe to copy. For other types copies must be made
19-
//! explicitly, by convention implementing the `Clone` trait and calling
20-
//! the `clone` method.
19+
//! explicitly, by convention implementing the [`Clone`] trait and calling
20+
//! the [`clone`][clone] method.
21+
//!
22+
//! [`Clone`]: trait.Clone.html
23+
//! [clone]: trait.Clone.html#tymethod.clone
24+
//! [`Drop`]: ../../std/ops/trait.Drop.html
2125
//!
2226
//! Basic usage example:
2327
//!
@@ -46,22 +50,22 @@
4650

4751
/// A common trait for the ability to explicitly duplicate an object.
4852
///
49-
/// Differs from `Copy` in that `Copy` is implicit and extremely inexpensive, while
53+
/// Differs from [`Copy`] in that [`Copy`] is implicit and extremely inexpensive, while
5054
/// `Clone` is always explicit and may or may not be expensive. In order to enforce
51-
/// these characteristics, Rust does not allow you to reimplement `Copy`, but you
55+
/// these characteristics, Rust does not allow you to reimplement [`Copy`], but you
5256
/// may reimplement `Clone` and run arbitrary code.
5357
///
54-
/// Since `Clone` is more general than `Copy`, you can automatically make anything
55-
/// `Copy` be `Clone` as well.
58+
/// Since `Clone` is more general than [`Copy`], you can automatically make anything
59+
/// [`Copy`] be `Clone` as well.
5660
///
5761
/// ## Derivable
5862
///
5963
/// This trait can be used with `#[derive]` if all fields are `Clone`. The `derive`d
60-
/// implementation of `clone()` calls `clone()` on each field.
64+
/// implementation of [`clone()`] calls [`clone()`] on each field.
6165
///
6266
/// ## How can I implement `Clone`?
6367
///
64-
/// Types that are `Copy` should have a trivial implementation of `Clone`. More formally:
68+
/// Types that are [`Copy`] should have a trivial implementation of `Clone`. More formally:
6569
/// if `T: Copy`, `x: T`, and `y: &T`, then `let x = y.clone();` is equivalent to `let x = *y;`.
6670
/// Manual implementations should be careful to uphold this invariant; however, unsafe code
6771
/// must not rely on it to ensure memory safety.
@@ -70,6 +74,9 @@
7074
/// library only implements `Clone` up until arrays of size 32. In this case, the implementation of
7175
/// `Clone` cannot be `derive`d, but can be implemented as:
7276
///
77+
/// [`Copy`]: ../../std/marker/trait.Copy.html
78+
/// [`clone()`]: trait.Clone.html#tymethod.clone
79+
///
7380
/// ```
7481
/// #[derive(Copy)]
7582
/// struct Stats {

src/libcore/marker.rs

Lines changed: 35 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,7 @@ pub trait Unsize<T: ?Sized> {
126126
/// }
127127
/// ```
128128
///
129-
/// The `PointList` `struct` cannot implement `Copy`, because `Vec<T>` is not `Copy`. If we
129+
/// The `PointList` `struct` cannot implement `Copy`, because [`Vec<T>`] is not `Copy`. If we
130130
/// attempt to derive a `Copy` implementation, we'll get an error:
131131
///
132132
/// ```text
@@ -136,10 +136,10 @@ pub trait Unsize<T: ?Sized> {
136136
/// ## When can my type _not_ be `Copy`?
137137
///
138138
/// Some types can't be copied safely. For example, copying `&mut T` would create an aliased
139-
/// mutable reference, and copying `String` would result in two attempts to free the same buffer.
139+
/// mutable reference, and copying [`String`] would result in two attempts to free the same buffer.
140140
///
141-
/// Generalizing the latter case, any type implementing `Drop` can't be `Copy`, because it's
142-
/// managing some resource besides its own `size_of::<T>()` bytes.
141+
/// Generalizing the latter case, any type implementing [`Drop`] can't be `Copy`, because it's
142+
/// managing some resource besides its own [`size_of::<T>()`] bytes.
143143
///
144144
/// ## What if I derive `Copy` on a type that can't?
145145
///
@@ -156,8 +156,7 @@ pub trait Unsize<T: ?Sized> {
156156
///
157157
/// ## Derivable
158158
///
159-
/// This trait can be used with `#[derive]` if all of its components implement `Copy` and the type
160-
/// implements `Clone`. The implementation will copy the bytes of each field using `memcpy`.
159+
/// This trait can be used with `#[derive]` if all of its components implement `Copy` and the type.
161160
///
162161
/// ## How can I implement `Copy`?
163162
///
@@ -178,6 +177,11 @@ pub trait Unsize<T: ?Sized> {
178177
///
179178
/// There is a small difference between the two: the `derive` strategy will also place a `Copy`
180179
/// bound on type parameters, which isn't always desired.
180+
///
181+
/// [`Vec<T>`]: ../../std/vec/struct.Vec.html
182+
/// [`String`]: ../../std/string/struct.String.html
183+
/// [`Drop`]: ../../std/ops/trait.Drop.html
184+
/// [`size_of::<T>()`]: ../../std/mem/fn.size_of.html
181185
#[stable(feature = "rust1", since = "1.0.0")]
182186
#[lang = "copy"]
183187
pub trait Copy : Clone {
@@ -190,11 +194,11 @@ pub trait Copy : Clone {
190194
/// thread-safe. In other words, there is no possibility of data races
191195
/// when passing `&T` references between threads.
192196
///
193-
/// As one would expect, primitive types like `u8` and `f64` are all
197+
/// As one would expect, primitive types like [`u8`] and [`f64`] are all
194198
/// `Sync`, and so are simple aggregate types containing them (like
195199
/// tuples, structs and enums). More instances of basic `Sync` types
196200
/// include "immutable" types like `&T` and those with simple
197-
/// inherited mutability, such as `Box<T>`, `Vec<T>` and most other
201+
/// inherited mutability, such as [`Box<T>`], [`Vec<T>`] and most other
198202
/// collection types. (Generic parameters need to be `Sync` for their
199203
/// container to be `Sync`.)
200204
///
@@ -206,27 +210,42 @@ pub trait Copy : Clone {
206210
/// race.
207211
///
208212
/// Types that are not `Sync` are those that have "interior
209-
/// mutability" in a non-thread-safe way, such as `Cell` and `RefCell`
210-
/// in `std::cell`. These types allow for mutation of their contents
213+
/// mutability" in a non-thread-safe way, such as [`Cell`] and [`RefCell`]
214+
/// in [`std::cell`]. These types allow for mutation of their contents
211215
/// even when in an immutable, aliasable slot, e.g. the contents of
212-
/// `&Cell<T>` can be `.set`, and do not ensure data races are
216+
/// [`&Cell<T>`][`Cell`] can be [`.set`], and do not ensure data races are
213217
/// impossible, hence they cannot be `Sync`. A higher level example
214218
/// of a non-`Sync` type is the reference counted pointer
215-
/// `std::rc::Rc`, because any reference `&Rc<T>` can clone a new
219+
/// [`std::rc::Rc`][`Rc`], because any reference [`&Rc<T>`][`Rc`] can clone a new
216220
/// reference, which modifies the reference counts in a non-atomic
217221
/// way.
218222
///
219223
/// For cases when one does need thread-safe interior mutability,
220-
/// types like the atomics in `std::sync` and `Mutex` & `RWLock` in
221-
/// the `sync` crate do ensure that any mutation cannot cause data
224+
/// types like the atomics in [`std::sync`][`sync`] and [`Mutex`] / [`RwLock`] in
225+
/// the [`sync`] crate do ensure that any mutation cannot cause data
222226
/// races. Hence these types are `Sync`.
223227
///
224-
/// Any types with interior mutability must also use the `std::cell::UnsafeCell`
228+
/// Any types with interior mutability must also use the [`std::cell::UnsafeCell`]
225229
/// wrapper around the value(s) which can be mutated when behind a `&`
226230
/// reference; not doing this is undefined behavior (for example,
227-
/// `transmute`-ing from `&T` to `&mut T` is invalid).
231+
/// [`transmute`]-ing from `&T` to `&mut T` is invalid).
228232
///
229233
/// This trait is automatically derived when the compiler determines it's appropriate.
234+
///
235+
/// [`u8`]: ../../std/primitive.u8.html
236+
/// [`f64`]: ../../std/primitive.f64.html
237+
/// [`Vec<T>`]: ../../std/vec/struct.Vec.html
238+
/// [`Box<T>`]: ../../std/boxed/struct.Box.html
239+
/// [`Cell`]: ../../std/cell/struct.Cell.html
240+
/// [`RefCell`]: ../../std/cell/struct.RefCell.html
241+
/// [`std::cell`]: ../../std/cell/index.html
242+
/// [`.set`]: ../../std/cell/struct.Cell.html#method.set
243+
/// [`Rc`]: ../../std/rc/struct.Rc.html
244+
/// [`sync`]: ../../std/sync/index.html
245+
/// [`Mutex`]: ../../std/sync/struct.Mutex.html
246+
/// [`RwLock`]: ../../std/sync/struct.RwLock.html
247+
/// [`std::cell::UnsafeCell`]: ../../std/cell/struct.UnsafeCell.html
248+
/// [`transmute`]: ../../std/mem/fn.transmute.html
230249
#[stable(feature = "rust1", since = "1.0.0")]
231250
#[lang = "sync"]
232251
#[rustc_on_unimplemented = "`{Self}` cannot be shared between threads safely"]

src/libcore/option.rs

Lines changed: 50 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,9 @@
1010

1111
//! Optional values.
1212
//!
13-
//! Type `Option` represents an optional value: every `Option`
14-
//! is either `Some` and contains a value, or `None`, and
15-
//! does not. `Option` types are very common in Rust code, as
13+
//! Type [`Option`] represents an optional value: every [`Option`]
14+
//! is either [`Some`] and contains a value, or [`None`], and
15+
//! does not. [`Option`] types are very common in Rust code, as
1616
//! they have a number of uses:
1717
//!
1818
//! * Initial values
@@ -26,8 +26,8 @@
2626
//! * Nullable pointers
2727
//! * Swapping things out of difficult situations
2828
//!
29-
//! Options are commonly paired with pattern matching to query the presence
30-
//! of a value and take action, always accounting for the `None` case.
29+
//! [`Option`]s are commonly paired with pattern matching to query the presence
30+
//! of a value and take action, always accounting for the [`None`] case.
3131
//!
3232
//! ```
3333
//! fn divide(numerator: f64, denominator: f64) -> Option<f64> {
@@ -57,13 +57,13 @@
5757
//!
5858
//! Rust's pointer types must always point to a valid location; there are
5959
//! no "null" pointers. Instead, Rust has *optional* pointers, like
60-
//! the optional owned box, `Option<Box<T>>`.
60+
//! the optional owned box, [`Option`]`<`[`Box<T>`]`>`.
6161
//!
62-
//! The following example uses `Option` to create an optional box of
63-
//! `i32`. Notice that in order to use the inner `i32` value first the
62+
//! The following example uses [`Option`] to create an optional box of
63+
//! [`i32`]. Notice that in order to use the inner [`i32`] value first the
6464
//! `check_optional` function needs to use pattern matching to
65-
//! determine whether the box has a value (i.e. it is `Some(...)`) or
66-
//! not (`None`).
65+
//! determine whether the box has a value (i.e. it is [`Some(...)`][`Some`]) or
66+
//! not ([`None`]).
6767
//!
6868
//! ```
6969
//! let optional: Option<Box<i32>> = None;
@@ -80,14 +80,14 @@
8080
//! }
8181
//! ```
8282
//!
83-
//! This usage of `Option` to create safe nullable pointers is so
83+
//! This usage of [`Option`] to create safe nullable pointers is so
8484
//! common that Rust does special optimizations to make the
85-
//! representation of `Option<Box<T>>` a single pointer. Optional pointers
85+
//! representation of [`Option`]`<`[`Box<T>`]`>` a single pointer. Optional pointers
8686
//! in Rust are stored as efficiently as any other pointer type.
8787
//!
8888
//! # Examples
8989
//!
90-
//! Basic pattern matching on `Option`:
90+
//! Basic pattern matching on [`Option`]:
9191
//!
9292
//! ```
9393
//! let msg = Some("howdy");
@@ -101,7 +101,7 @@
101101
//! let unwrapped_msg = msg.unwrap_or("default message");
102102
//! ```
103103
//!
104-
//! Initialize a result to `None` before a loop:
104+
//! Initialize a result to [`None`] before a loop:
105105
//!
106106
//! ```
107107
//! enum Kingdom { Plant(u32, &'static str), Animal(u32, &'static str) }
@@ -136,6 +136,12 @@
136136
//! None => println!("there are no animals :("),
137137
//! }
138138
//! ```
139+
//!
140+
//! [`Option`]: enum.Option.html
141+
//! [`Some`]: enum.Option.html#variant.Some
142+
//! [`None`]: enum.Option.html#variant.None
143+
//! [`Box<T>`]: ../../std/boxed/struct.Box.html
144+
//! [`i32`]: ../../std/primitive.i32.html
139145
140146
#![stable(feature = "rust1", since = "1.0.0")]
141147

@@ -156,7 +162,7 @@ pub enum Option<T> {
156162
None,
157163
/// Some value `T`
158164
#[stable(feature = "rust1", since = "1.0.0")]
159-
Some(#[stable(feature = "rust1", since = "1.0.0")] T)
165+
Some(#[stable(feature = "rust1", since = "1.0.0")] T),
160166
}
161167

162168
/////////////////////////////////////////////////////////////////////////////
@@ -168,7 +174,7 @@ impl<T> Option<T> {
168174
// Querying the contained values
169175
/////////////////////////////////////////////////////////////////////////
170176

171-
/// Returns `true` if the option is a `Some` value
177+
/// Returns `true` if the option is a `Some` value.
172178
///
173179
/// # Examples
174180
///
@@ -188,7 +194,7 @@ impl<T> Option<T> {
188194
}
189195
}
190196

191-
/// Returns `true` if the option is a `None` value
197+
/// Returns `true` if the option is a `None` value.
192198
///
193199
/// # Examples
194200
///
@@ -209,15 +215,17 @@ impl<T> Option<T> {
209215
// Adapter for working with references
210216
/////////////////////////////////////////////////////////////////////////
211217

212-
/// Converts from `Option<T>` to `Option<&T>`
218+
/// Converts from `Option<T>` to `Option<&T>`.
213219
///
214220
/// # Examples
215221
///
216222
/// Convert an `Option<String>` into an `Option<usize>`, preserving the original.
217-
/// The `map` method takes the `self` argument by value, consuming the original,
223+
/// The [`map`] method takes the `self` argument by value, consuming the original,
218224
/// so this technique uses `as_ref` to first take an `Option` to a reference
219225
/// to the value inside the original.
220226
///
227+
/// [`map`]: enum.Option.html#method.map
228+
///
221229
/// ```
222230
/// let num_as_str: Option<String> = Some("10".to_string());
223231
/// // First, cast `Option<String>` to `Option<&String>` with `as_ref`,
@@ -234,7 +242,7 @@ impl<T> Option<T> {
234242
}
235243
}
236244

237-
/// Converts from `Option<T>` to `Option<&mut T>`
245+
/// Converts from `Option<T>` to `Option<&mut T>`.
238246
///
239247
/// # Examples
240248
///
@@ -357,7 +365,7 @@ impl<T> Option<T> {
357365
// Transforming contained values
358366
/////////////////////////////////////////////////////////////////////////
359367

360-
/// Maps an `Option<T>` to `Option<U>` by applying a function to a contained value
368+
/// Maps an `Option<T>` to `Option<U>` by applying a function to a contained value.
361369
///
362370
/// # Examples
363371
///
@@ -423,8 +431,12 @@ impl<T> Option<T> {
423431
}
424432
}
425433

426-
/// Transforms the `Option<T>` into a `Result<T, E>`, mapping `Some(v)` to
427-
/// `Ok(v)` and `None` to `Err(err)`.
434+
/// Transforms the `Option<T>` into a [`Result<T, E>`], mapping `Some(v)` to
435+
/// [`Ok(v)`] and `None` to [`Err(err)`][Err].
436+
///
437+
/// [`Result<T, E>`]: ../../std/result/enum.Result.html
438+
/// [`Ok(v)`]: ../../std/result/enum.Result.html#variant.Ok
439+
/// [Err]: ../../std/result/enum.Result.html#variant.Err
428440
///
429441
/// # Examples
430442
///
@@ -444,8 +456,12 @@ impl<T> Option<T> {
444456
}
445457
}
446458

447-
/// Transforms the `Option<T>` into a `Result<T, E>`, mapping `Some(v)` to
448-
/// `Ok(v)` and `None` to `Err(err())`.
459+
/// Transforms the `Option<T>` into a [`Result<T, E>`], mapping `Some(v)` to
460+
/// [`Ok(v)`] and `None` to [`Err(err())`][Err].
461+
///
462+
/// [`Result<T, E>`]: ../../std/result/enum.Result.html
463+
/// [`Ok(v)`]: ../../std/result/enum.Result.html#variant.Ok
464+
/// [Err]: ../../std/result/enum.Result.html#variant.Err
449465
///
450466
/// # Examples
451467
///
@@ -789,7 +805,9 @@ impl<A> DoubleEndedIterator for Item<A> {
789805
impl<A> ExactSizeIterator for Item<A> {}
790806
impl<A> FusedIterator for Item<A> {}
791807

792-
/// An iterator over a reference of the contained item in an Option.
808+
/// An iterator over a reference of the contained item in an [`Option`].
809+
///
810+
/// [`Option`]: enum.Option.html
793811
#[stable(feature = "rust1", since = "1.0.0")]
794812
#[derive(Debug)]
795813
pub struct Iter<'a, A: 'a> { inner: Item<&'a A> }
@@ -823,7 +841,9 @@ impl<'a, A> Clone for Iter<'a, A> {
823841
}
824842
}
825843

826-
/// An iterator over a mutable reference of the contained item in an Option.
844+
/// An iterator over a mutable reference of the contained item in an [`Option`].
845+
///
846+
/// [`Option`]: enum.Option.html
827847
#[stable(feature = "rust1", since = "1.0.0")]
828848
#[derive(Debug)]
829849
pub struct IterMut<'a, A: 'a> { inner: Item<&'a mut A> }
@@ -850,7 +870,9 @@ impl<'a, A> ExactSizeIterator for IterMut<'a, A> {}
850870
#[unstable(feature = "fused", issue = "35602")]
851871
impl<'a, A> FusedIterator for IterMut<'a, A> {}
852872

853-
/// An iterator over the item contained inside an Option.
873+
/// An iterator over the item contained inside an [`Option`].
874+
///
875+
/// [`Option`]: enum.Option.html
854876
#[derive(Clone, Debug)]
855877
#[stable(feature = "rust1", since = "1.0.0")]
856878
pub struct IntoIter<A> { inner: Item<A> }

0 commit comments

Comments
 (0)