Navigation Menu

Skip to content

Commit

Permalink
std: Refining crate docs
Browse files Browse the repository at this point in the history 
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.
  • Loading branch information
@brson
brson committed Jul 14, 2015
1 parent 72483f5 commit 68781e2
Show file tree
Hide file tree
Showing 2 changed files with 217 additions and 33 deletions.
147 changes: 121 additions & 26 deletions src/libstd/lib.rs
View file
Expand Up @@ -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 <a href="#"
//! onclick="document.getElementsByName('search')[0].focus();">search
//! bar</a> 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
//!
Expand All @@ -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
Expand Down Expand Up @@ -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))]
Expand Down
103 changes: 96 additions & 7 deletions src/libstd/prelude/mod.rs
View file
Expand Up @@ -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")]

Expand Down

0 comments on commit 68781e2

Please sign in to comment.