From 68781e25c5465021d25e2ff9d3818577e70c6545 Mon Sep 17 00:00:00 2001 From: Brian Anderson Date: Sat, 11 Jul 2015 12:12:19 -0700 Subject: [PATCH] std: Refining crate docs Yet another attempt to make the prose on the std crate page clearer and more informative. This does a lot of things: tightens up the opening, adds useful links (including a link to the search bar), offers guidance on how to use the docs, and expands the prelude docs as a useful newbie entrypoint. --- src/libstd/lib.rs | 147 +++++++++++++++++++++++++++++++------- src/libstd/prelude/mod.rs | 103 ++++++++++++++++++++++++-- 2 files changed, 217 insertions(+), 33 deletions(-) diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs index 1e82a03f28630..e6049ab286356 100644 --- a/src/libstd/lib.rs +++ b/src/libstd/lib.rs @@ -10,29 +10,122 @@ //! # The Rust Standard Library //! -//! The Rust Standard Library provides the essential runtime -//! functionality for building portable Rust software. +//! The Rust Standard Library is the foundation of portable Rust +//! software, a set of minimal and battle-tested shared abstractions +//! for the [broader Rust ecosystem](https://crates.io). It offers +//! core types (e.g. [`Vec`](vec/index.html) +//! and[`Option`](option/index.html)), library-defined [operations on +//! language primitives](#primitive) (e.g. [`u32`](u32/index.html) and +//! [`str`](str/index.html)), [standard macros](#macros), +//! [I/O](io/index.html) and [multithreading](thread/index.html), among +//! [many other lovely +//! things](#what-is-in-the-standard-library-documentation?). //! -//! The Rust Standard Library is available to all Rust crates by -//! default, just as if contained an `extern crate std` import at the -//! crate root. Therefore the standard library can be accessed in -//! `use` statements through the path `std`, as in `use std::thread`, -//! or in expressions through the absolute path `::std`, as in -//! `::std::thread::sleep_ms(100)`. +//! `std` is available to all Rust crates by default, just as if each +//! one contained an `extern crate std` import at the [crate +//! root][book-crate-root]. Therefore the standard library can be +//! accessed in [`use`][book-use] statements through the path `std`, +//! as in [`use std::env`](env/index.html), or in expressions +//! through the absolute path `::std`, as in +//! [`::std::env::args()`](env/fn.args.html). +//! +//! [book-crate-root]: file:///home/brian/dev/rust2/build/doc/book/crates-and-modules.html#basic-terminology:-crates-and-modules +//! [book-use]: ../book/crates-and-modules.html#importing-modules-with-use //! //! Furthermore, the standard library defines [The Rust //! Prelude](prelude/index.html), a small collection of items, mostly -//! traits, that are imported into and available in every module. +//! traits, that are imported into every module and through trait +//! resolution provide Rust with much of its *standard flavor*. +//! +//! # How to read this documentation +//! +//! If you already know the name of what you are looking for the +//! fastest way to find it is to use the search +//! bar at the top of the page. +//! +//! Otherwise, you may want to jump to one of these useful sections: +//! +//! * [`std::*` modules](#modules) +//! * [Primitive types](#primitives) +//! * [Standard macros](#macros) +//! * [The Rust Prelude](prelude/index.html) +//! +//! If this is your first time, the documentation for the standard +//! library is written to be casually perused and clicking on +//! interesting things should generally lead you to interesting +//! places. Still, there are important bits you don't want to miss, so +//! read on for a tour of the standard library and its documentation. +//! +//! Once you are familiar with the contents of the standard library +//! you may begin to find the verbosity of the prose distracting. At +//! this stage in your development you may want to press the **[-]** +//! button near the top of the page to collapse it into a more +//! skimmable view. +//! +//! While you are looking at that **[-]** button also notice the +//! **[src]** button. Rust's API documentation comes with the source +//! code and you are encouraged to read it. The standard library +//! source is generally high quality and a peek behind the curtains is +//! often enlightening. +//! +//! # What is in the standard library documentation? //! -//! ## What is in the standard library +//! Lots of stuff. Well, broadly four things actually. //! -//! The standard library is a set of minimal, battle-tested -//! core types and shared abstractions for the [broader Rust -//! ecosystem](https://crates.io) to build on. +//! First of all, The Rust Standard Library is divided into a number +//! of focused modules, [all listed further down this page](#modules). +//! These modules are the bedrock upon which all of Rust is forged, +//! and they have mighty names like [`std::slice`](slice/index.html) +//! and [`std::cmp`](cmp/index.html). Modules' documentation typically +//! includes an overview of the module along with examples, and are +//! a smart place to start familiarizing yourself with the library. //! -//! The [primitive types](#primitives), though not defined in the -//! standard library, are documented here, as are the predefined -//! [macros](#macros). +//! Secondly, implicit methods on [primitive +//! types](../book/primitive-types.html) are documented here. This can +//! be a source of confusion for two reasons: +//! +//! 1. While primitives are implemented by the compiler, the standard +//! library implements methods directly on the primitive types (and +//! it is the only library that does so), which are [documented in +//! the section on primitives](#primitives). +//! 2. The standard library exports many modules *with the same name +//! as primitive types*. These define additional items related +//! to the primitive type, but not the all-important methods. +//! +//! So for example there is a [page for the primitive type +//! `i32`](primitive.i32.html) that lists all the methods that can be +//! called on 32-bit integers (mega useful), and there is a [page for +//! the module `std::i32`](i32/index.html) that documents the constant +//! values `MIN` and `MAX` (rarely useful). +//! +//! Note the documentation for the primitives +//! [`str`](primitive.str.html) and [`[T]`](primitive.slice.html) +//! (also called 'slice'). Many method calls on +//! [`String`](string/struct.String.html) and +//! [`Vec`](vec/struct.Vec.html) are actually calls to methods on +//! `str` and `[T]` respectively, via [deref +//! coercions](../book/deref-coercions.html). *Accepting that +//! primitive types are documented on their own pages will bring you a +//! deep inner wisdom. Embrace it now before proceeding.* +//! +//! Thirdly, the standard library defines [The Rust +//! Prelude](prelude/index.html), a small collection of items - mostly +//! traits - that are imported into every module. The traits in the +//! prelude are pervasive, making the prelude documentation a good +//! entry point to learning about the library. +//! +//! And lastly, the standard library exports a number of standard +//! macros, and [lists them on this page](#macros) (technically, not +//! all of the standard macros are defined by the standard library - +//! some are defined by the compiler - but they are documented here +//! the same). Like the prelude, the standard macros are imported by +//! default into all crates. +//! +//! # A Tour of The Rust Standard Library +//! +//! The rest of this crate documentation is dedicated to pointing +//! out notable features of The Rust Standard Library. //! //! ## Containers and collections //! @@ -43,17 +136,18 @@ //! [`Iterator`](iter/trait.Iterator.html), which works with the `for` //! loop to access collections. //! -//! The common container type, `Vec`, a growable vector backed by an array, -//! lives in the [`vec`](vec/index.html) module. Contiguous, unsized regions -//! of memory, `[T]`, commonly called "slices", and their borrowed versions, -//! `&[T]`, commonly called "borrowed slices", are built-in types for which the -//! [`slice`](slice/index.html) module defines many methods. +//! The common container type, `Vec`, a growable vector backed by an +//! array, lives in the [`vec`](vec/index.html) module. Contiguous, +//! unsized regions of memory, `[T]`, commonly called "slices", and +//! their borrowed versions, `&[T]`, commonly called "borrowed +//! slices", are primitive types [with many implicit +//! methods](primitive.slice.html) defined by the standard library. //! -//! `&str`, a UTF-8 string, is a built-in type, and the standard library -//! defines methods for it on a variety of traits in the -//! [`str`](str/index.html) module. Rust strings are immutable; -//! use the `String` type defined in [`string`](string/index.html) -//! for a mutable string builder. +//! `str`, a UTF-8 string, is a primitive type, and the standard +//! library defines [many methods for it](primitive.str.html). +//! Rust `str`s are immutable; use the owned `String` type +//! defined in [`string`](string/index.html) for building and mutating +//! strings. //! //! For converting to strings use the [`format!`](fmt/index.html) //! macro, and for converting from strings use the @@ -88,6 +182,7 @@ //! [`atomic`](sync/atomic/index.html) and //! [`mpsc`](sync/mpsc/index.html), which contains the channel types //! for message passing. +//! // Do not remove on snapshot creation. Needed for bootstrap. (Issue #22364) #![cfg_attr(stage0, feature(custom_attribute))] diff --git a/src/libstd/prelude/mod.rs b/src/libstd/prelude/mod.rs index 156a3d428debd..bb1041a76c81c 100644 --- a/src/libstd/prelude/mod.rs +++ b/src/libstd/prelude/mod.rs @@ -22,18 +22,107 @@ //! with the `std::` path prefix, as in `use std::vec`, `use std::thread::spawn`, //! etc. //! -//! Additionally, `std` contains a `prelude` module that reexports many of the -//! most common traits, types and functions. The contents of the prelude are -//! imported into every *module* by default. Implicitly, all modules behave as if -//! they contained the following prologue: +//! Additionally, `std` contains a versioned *prelude* that reexports many of the +//! most common traits, types and functions. *The contents of the prelude are +//! imported into every module by default*. Implicitly, all modules behave as if +//! they contained the following [`use` statement][book-use]: +//! +//! [book-use]: ../../book/crates-and-modules.html#importing-modules-with-use //! //! ```ignore //! use std::prelude::v1::*; //! ``` //! -//! The prelude is primarily concerned with exporting *traits* that are so -//! pervasive that it would be obnoxious to import for every use, particularly -//! those that define methods on primitive types. +//! The prelude is primarily concerned with exporting *traits* that +//! are so pervasive that it would be onerous to import for every use, +//! particularly those that are commonly mentioned in [generic type +//! bounds][book-traits], and that are often used +//! +//! The current version of the prelude (version 1) lives in +//! [`std::prelude::v1`](v1/index.html), and reexports the following. +//! +//! * `std::marker::`{ +//! [`Copy`](../marker/trait.Copy.html), +//! [`Send`](../marker/trait.Send.html), +//! [`Sized`](../marker/trait.Sized.html), +//! [`Sync`](../marker/trait.Sync.html) +//! }. +//! The marker traits indicate fundamental properties of types. +//! * `std::ops::`{ +//! [`Drop`](../ops/trait.Drop.html), +//! [`Fn`](../ops/trait.Fn.html), +//! [`FnMut`](../ops/trait.FnMut.html), +//! [`FnOnce`](../ops/trait.FnOnce.html) +//! }. +//! The [destructor][book-dtor] trait and the +//! [closure][book-closures] traits, reexported from the same +//! [module that also defines overloaded +//! operators](../ops/index.html). +//! * `std::mem::`[`drop`](../mem/fn.drop.html). +//! A convenience function for explicitly dropping a value. +//! * `std::boxed::`[`Box`](../boxed/struct.Box.html). +//! The owned heap pointer. +//! * `std::borrow::`[`ToOwned`](../borrow/trait.ToOwned.html). +//! The conversion trait that defines `to_owned`, the generic method +//! for creating an owned type from a borrowed type. +//! * `std::clone::`[`Clone`](../clone/trait.Clone.html). +//! The ubiquitous trait that defines `clone`, the method for +//! producing copies of values that are consider expensive to copy. +//! * `std::cmp::`{ +//! [`PartialEq`](../cmp/trait.PartialEq.html), +//! [`PartialOrd`](../cmp/trait.PartialOrd.html), +//! [`Eq`](../cmp/trait.Eq.html), +//! [`Ord`](../cmp/trait.Ord.html) +//! }. +//! The comparision traits, which implement the comparison operators +//! and are often seen in trait bounds. +//! * `std::convert::`{ +//! [`AsRef`](../convert/trait.AsRef.html), +//! [`AsMut`](../convert/trait.AsMut.html), +//! [`Into`](../convert/trait.Into.html), +//! [`From`](../convert/trait.From.html) +//! }. +//! Generic conversions, used by savvy API authors to create +//! overloaded methods. +//! * `std::default::`[`Default`](../default/trait.Default). +//! Types that have default values. +//! * `std::iter::`{ +//! [`Iterator`](../iter/trait.Iterator.html), +//! [`Extend`](../iter/trait.Extend.html), +//! [`IntoIterator`](../iter/trait.IntoIterator.html), +//! [`DoubleEndedIterator`](../iter/trait.DoubleEndedIterator.html), +//! [`ExactSizeIterator`](../iter/trait.ExactSizeIterator.html) +//! }. +//! [Iterators][book-iter]. +//! * `std::option::Option::`{ +//! [`self`](../option/enum.Option.html), +//! [`Some`](../option/enum.Option.html), +//! [`None`](../option/enum.Option.html) +//! }. +//! The ubiquitous `Option` type and its two [variants][book-enums], +//! `Some` and `None`. +//! * `std::result::Result::`{ +//! [`self`](../result/enum.Result.html), +//! [`Some`](../result/enum.Result.html), +//! [`None`](../result/enum.Result.html) +//! }. +//! The ubiquitous `Result` type and its two [variants][book-enums], +//! `Ok` and `Err`. +//! * `std::slice::`[`SliceConcatExt`](../slice/trait.SliceConcatExt.html). +//! An unstable extension to slices that shouldn't have to exist. +//! * `std::string::`{ +//! [`String`](../string/struct.String.html), +//! [`ToString`](../string/trait.ToString.html) +//! }. +//! Heap allocated strings. +//! * `std::vec::`[`Vec`](../vec/struct.Vec.html). +//! Heap allocated vectors. +//! +//! [book-traits]: ../../book/traits.html +//! [book-closures]: ../../book/closures.html +//! [book-dtor]: ../../book/drop.html +//! [book-iter]: ../../book/iterators.html +//! [book-enums]: ../../book/enums.html #![stable(feature = "rust1", since = "1.0.0")]