Skip to content

Commit a1b2476

Browse files
steveklabniksteveklabnik
committed
Clean up the prelude docs
This mostly brings them in line with existing linking convention, but also has some minor re-wording. The text at the top has been re-focused, by starting out with what the prelude does, rather than starting from injecting std. Also, it now mentions that other preludes exist. Part of #29369
1 parent f1f5c04 commit a1b2476

File tree

2 files changed

+115
-96
lines changed

2 files changed

+115
-96
lines changed

‎src/libstd/prelude/mod.rs

+113-96
Original file line numberDiff line numberDiff line change
@@ -10,119 +10,136 @@
1010

1111
//! The Rust Prelude
1212
//!
13-
//! Because `std` is required by most serious Rust software, it is
14-
//! imported at the topmost level of every crate by default, as if
15-
//! each crate contains the following:
13+
//! Rust comes with a variety of things in its standard library. However, if
14+
//! you had to manually import every single thing that you used, it would be
15+
//! very verbose. But importing a lot of things that a program never uses isn't
16+
//! good either. A balance needs to be struck.
17+
//!
18+
//! The *prelude* is the list of things that Rust automatically imports into
19+
//! every Rust program. It's kept as small as possible, and is focused on
20+
//! things, particuarly traits, which are used in almost every single Rust
21+
//! program.
22+
//!
23+
//! On a technical level, Rust inserts
1624
//!
1725
//! ```ignore
1826
//! extern crate std;
1927
//! ```
2028
//!
21-
//! This means that the contents of std can be accessed from any context
22-
//! with the `std::` path prefix, as in `use std::vec`, `use std::thread::spawn`,
23-
//! etc.
24-
//!
25-
//! Additionally, `std` contains a versioned *prelude* that reexports many of the
26-
//! most common traits, types, and functions. *The contents of the prelude are
27-
//! imported into every module by default*. Implicitly, all modules behave as if
28-
//! they contained the following [`use` statement][book-use]:
29-
//!
30-
//! [book-use]: ../../book/crates-and-modules.html#importing-modules-with-use
29+
//! into the crate root of every crate, and
3130
//!
3231
//! ```ignore
3332
//! use std::prelude::v1::*;
3433
//! ```
3534
//!
36-
//! The prelude is primarily concerned with exporting *traits* that
37-
//! are so pervasive that they would be onerous to import for every use,
38-
//! particularly those that are commonly mentioned in [generic type
39-
//! bounds][book-traits].
35+
//! into every module.
36+
//!
37+
//! # Other preludes
38+
//!
39+
//! Preludes can be seen as a pattern to make using multiple types more
40+
//! convenient. As such, you'll find other preludes in the standard library,
41+
//! such as [`std::io::prelude`]. Various libraries in the Rust ecosystem may
42+
//! also define their own preludes.
43+
//!
44+
//! [`std::io::prelude`]: ../io/prelude/index.html
45+
//!
46+
//! The differece between 'the prelude' and these other preludes is that they
47+
//! are not automatically `use`'d, and must be imported manually. This is still
48+
//! easier than importing all of their consitutent components.
49+
//!
50+
//! # Prelude contents
4051
//!
4152
//! The current version of the prelude (version 1) lives in
42-
//! [`std::prelude::v1`](v1/index.html), and reexports the following.
53+
//! [`std::prelude::v1`], and reexports the following.
4354
//!
44-
//! * `std::marker::`{
45-
//! [`Copy`](../marker/trait.Copy.html),
46-
//! [`Send`](../marker/trait.Send.html),
47-
//! [`Sized`](../marker/trait.Sized.html),
48-
//! [`Sync`](../marker/trait.Sync.html)
49-
//! }.
50-
//! The marker traits indicate fundamental properties of types.
51-
//! * `std::ops::`{
52-
//! [`Drop`](../ops/trait.Drop.html),
53-
//! [`Fn`](../ops/trait.Fn.html),
54-
//! [`FnMut`](../ops/trait.FnMut.html),
55-
//! [`FnOnce`](../ops/trait.FnOnce.html)
56-
//! }.
57-
//! The [destructor][book-dtor] trait and the
58-
//! [closure][book-closures] traits, reexported from the same
59-
//! [module that also defines overloaded
60-
//! operators](../ops/index.html).
61-
//! * `std::mem::`[`drop`](../mem/fn.drop.html).
62-
//! A convenience function for explicitly dropping a value.
63-
//! * `std::boxed::`[`Box`](../boxed/struct.Box.html).
64-
//! The owned heap pointer.
65-
//! * `std::borrow::`[`ToOwned`](../borrow/trait.ToOwned.html).
66-
//! The conversion trait that defines `to_owned`, the generic method
67-
//! for creating an owned type from a borrowed type.
68-
//! * `std::clone::`[`Clone`](../clone/trait.Clone.html).
69-
//! The ubiquitous trait that defines `clone`, the method for
70-
//! producing copies of values that are consider expensive to copy.
71-
//! * `std::cmp::`{
72-
//! [`PartialEq`](../cmp/trait.PartialEq.html),
73-
//! [`PartialOrd`](../cmp/trait.PartialOrd.html),
74-
//! [`Eq`](../cmp/trait.Eq.html),
75-
//! [`Ord`](../cmp/trait.Ord.html)
76-
//! }.
77-
//! The comparison traits, which implement the comparison operators
78-
//! and are often seen in trait bounds.
79-
//! * `std::convert::`{
80-
//! [`AsRef`](../convert/trait.AsRef.html),
81-
//! [`AsMut`](../convert/trait.AsMut.html),
82-
//! [`Into`](../convert/trait.Into.html),
83-
//! [`From`](../convert/trait.From.html)
84-
//! }.
85-
//! Generic conversions, used by savvy API authors to create
86-
//! overloaded methods.
87-
//! * `std::default::`[`Default`](../default/trait.Default.html).
88-
//! Types that have default values.
89-
//! * `std::iter::`{
90-
//! [`Iterator`](../iter/trait.Iterator.html),
91-
//! [`Extend`](../iter/trait.Extend.html),
92-
//! [`IntoIterator`](../iter/trait.IntoIterator.html),
93-
//! [`DoubleEndedIterator`](../iter/trait.DoubleEndedIterator.html),
94-
//! [`ExactSizeIterator`](../iter/trait.ExactSizeIterator.html)
95-
//! }.
96-
//! [Iterators][book-iter].
97-
//! * `std::option::Option::`{
98-
//! [`self`](../option/enum.Option.html),
99-
//! [`Some`](../option/enum.Option.html),
100-
//! [`None`](../option/enum.Option.html)
101-
//! }.
102-
//! The ubiquitous `Option` type and its two [variants][book-enums],
103-
//! `Some` and `None`.
104-
//! * `std::result::Result::`{
105-
//! [`self`](../result/enum.Result.html),
106-
//! [`Ok`](../result/enum.Result.html),
107-
//! [`Err`](../result/enum.Result.html)
108-
//! }.
109-
//! The ubiquitous `Result` type and its two [variants][book-enums],
110-
//! `Ok` and `Err`.
111-
//! * `std::slice::`[`SliceConcatExt`](../slice/trait.SliceConcatExt.html).
112-
//! An unstable extension to slices that shouldn't have to exist.
113-
//! * `std::string::`{
114-
//! [`String`](../string/struct.String.html),
115-
//! [`ToString`](../string/trait.ToString.html)
116-
//! }.
117-
//! Heap allocated strings.
118-
//! * `std::vec::`[`Vec`](../vec/struct.Vec.html).
119-
//! Heap allocated vectors.
55+
//! * [`std::marker`]::{[`Copy`], [`Send`], [`Sized`], [`Sync`]}. The marker
56+
//! traits indicate fundamental properties of types.
57+
//! * [`std::ops`]::{[`Drop`], [`Fn`], [`FnMut`], [`FnOnce`]}. Various
58+
//! operations for both destuctors and overloading `()`.
59+
//! * [`std::mem`]::[`drop`], a convenience function for explicitly dropping a
60+
//! value.
61+
//! * [`std::boxed`]::[`Box`], a way to allocate values on the heap.
62+
//! * [`std::borrow`]::[`ToOwned`], The conversion trait that defines
63+
//! [`to_owned()`], the generic method for creating an owned type from a
64+
//! borrowed type.
65+
//! * [`std::clone`]::[`Clone`], the ubiquitous trait that defines [`clone()`],
66+
//! the method for producing a copy of a value.
67+
//! * [`std::cmp`]::{[`PartialEq`], [`PartialOrd`], [`Eq`], [`Ord`] }. The
68+
//! comparison traits, which implement the comparison operators and are often
69+
//! seen in trait bounds.
70+
//! * [`std::convert`]::{[`AsRef`], [`AsMut`], [`Into`], [`From`]}. Generic
71+
//! conversions, used by savvy API authors to create overloaded methods.
72+
//! * [`std::default`]::[`Default`], types that have default values.
73+
//! * [`std::iter`]::{[`Iterator`], [`Extend`], [`IntoIterator`],
74+
//! [`DoubleEndedIterator`], [`ExactSizeIterator`]}. Iterators of various
75+
//! kinds.
76+
//! * [`std::option`]::[`Option`]::{`self`, `Some`, `None`}. A type which
77+
//! expresses the presence or absence of a value. This type is so commonly
78+
//! used, its variants are also exported.
79+
//! * [`std::result`]::[`Result`]::{`self`, `Ok`, `Err`}. A type for functions
80+
//! that may succeed or fail. Like [`Option`], its variants are exported as
81+
//! well.
82+
//! * [`std::slice`]::[`SliceConcatExt`], a trait that exists for technical
83+
//! reasons, but shouldn't have to exist. It provides a few useful methods on
84+
//! slices.
85+
//! * [`std::string`]::{[`String`], [`ToString`]}, heap allocated strings.
86+
//! * [`std::vec`]::[`Vec`](../vec/struct.Vec.html), a growable, heap-allocated
87+
//! vector.
12088
//!
121-
//! [book-traits]: ../../book/traits.html
89+
//! [`AsMut`]: ../convert/trait.AsMut.html
90+
//! [`AsRef`]: ../convert/trait.AsRef.html
91+
//! [`Box`]: ../boxed/struct.Box.html
92+
//! [`Clone`]: ../clone/trait.Clone.html
93+
//! [`Copy`]: ../marker/trait.Copy.html
94+
//! [`Default`]: ../default/trait.Default.html
95+
//! [`DoubleEndedIterator`]: ../iter/trait.DoubleEndedIterator.html
96+
//! [`Drop`]: ../ops/trait.Drop.html
97+
//! [`Eq`]: ../cmp/trait.Eq.html
98+
//! [`ExactSizeIterator`]: ../iter/trait.ExactSizeIterator.html
99+
//! [`Extend`]: ../iter/trait.Extend.html
100+
//! [`FnMut`]: ../ops/trait.FnMut.html
101+
//! [`FnOnce`]: ../ops/trait.FnOnce.html
102+
//! [`Fn`]: ../ops/trait.Fn.html
103+
//! [`From`]: ../convert/trait.From.html
104+
//! [`IntoIterator`]: ../iter/trait.IntoIterator.html
105+
//! [`Into`]: ../convert/trait.Into.html
106+
//! [`Iterator`]: ../iter/trait.Iterator.html
107+
//! [`Option`]: ../option/enum.Option.html
108+
//! [`Ord`]: ../cmp/trait.Ord.html
109+
//! [`PartialEq`]: ../cmp/trait.PartialEq.html
110+
//! [`PartialOrd`]: ../cmp/trait.PartialOrd.html
111+
//! [`Result`]: ../result/enum.Result.html
112+
//! [`Send`]: ../marker/trait.Send.html
113+
//! [`Sized`]: ../marker/trait.Sized.html
114+
//! [`SliceConcatExt`]: ../slice/trait.SliceConcatExt.html
115+
//! [`String`]: ../string/struct.String.html
116+
//! [`Sync`]: ../marker/trait.Sync.html
117+
//! [`ToOwned`]: ../borrow/trait.ToOwned.html
118+
//! [`ToString`]: ../string/trait.ToString.html
119+
//! [`Vec`]: ../vec/struct.Vec.html
120+
//! [`clone()`]: ../clone/trait.Clone.html#tymethod.clone
121+
//! [`drop`]: ../mem/fn.drop.html
122+
//! [`std::borrow`]: ../borrow/index.html
123+
//! [`std::boxed`]: ../boxed/index.html
124+
//! [`std::clone`]: ../clone/index.html
125+
//! [`std::cmp`]: ../cmp/index.html
126+
//! [`std::convert`]: ../convert/index.html
127+
//! [`std::default`]: ../default/index.html
128+
//! [`std::iter`]: ../iter/index.html
129+
//! [`std::marker`]: ../marker/index.html
130+
//! [`std::mem`]: ../mem/index.html
131+
//! [`std::ops`]: ../ops/index.html
132+
//! [`std::option`]: ../option/index.html
133+
//! [`std::prelude::v1`]: v1/index.html
134+
//! [`std::result`]: ../result/index.html
135+
//! [`std::slice`]: ../slice/index.html
136+
//! [`std::string`]: ../string/index.html
137+
//! [`std::vec`]: ../vec/index.html
138+
//! [`to_owned()`]: ../borrow/trait.ToOwned.html#tymethod.to_owned
122139
//! [book-closures]: ../../book/closures.html
123140
//! [book-dtor]: ../../book/drop.html
124-
//! [book-iter]: ../../book/iterators.html
125141
//! [book-enums]: ../../book/enums.html
142+
//! [book-iter]: ../../book/iterators.html
126143
127144
#![stable(feature = "rust1", since = "1.0.0")]
128145

‎src/libstd/prelude/v1.rs

+2
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@
99
// except according to those terms.
1010

1111
//! The first version of the prelude of The Rust Standard Library.
12+
//!
13+
//! See the [module-level documentation](../index.html) for more.
1214
1315
#![stable(feature = "rust1", since = "1.0.0")]
1416

0 commit comments

Comments
 (0)