From 078bd498b9fa6eab40df147ce6015ab9aae62b40 Mon Sep 17 00:00:00 2001 From: Steve Klabnik Date: Mon, 12 Jan 2015 16:59:34 -0500 Subject: [PATCH] Evaluate # fn in docs I searched for times when we were hiding functions with # in the documentation, and fixed them to not use it unless neccesary. I also made random improvements whenever I changed something. For example, I changed Example to Examples, for consistency. Fixes #13423 --- src/doc/trpl/threads.md | 82 ++++++++++++++++++++++----------------- src/libcore/cell.rs | 1 - src/libcore/finally.rs | 2 - src/libcore/macros.rs | 17 +++++--- src/libcore/marker.rs | 3 +- src/libcore/prelude.rs | 4 -- src/libcore/result.rs | 2 - src/libstd/fmt.rs | 11 +----- src/libstd/io/mod.rs | 27 ++++++------- src/libstd/io/net/pipe.rs | 2 - src/libstd/io/net/tcp.rs | 6 +-- src/libstd/io/timer.rs | 4 +- src/libstd/macros.rs | 20 +++++----- src/libstd/sync/future.rs | 16 +++++--- 14 files changed, 95 insertions(+), 102 deletions(-) diff --git a/src/doc/trpl/threads.md b/src/doc/trpl/threads.md index 4c6a7f1323f..df94e91067c 100644 --- a/src/doc/trpl/threads.md +++ b/src/doc/trpl/threads.md @@ -51,13 +51,15 @@ closure is limited to capturing `Send`-able data from its environment ensures that `spawn` can safely move the entire closure and all its associated state into an entirely different thread for execution. -```{rust,ignore} -# use std::thread::spawn; -# fn generate_thread_number() -> int { 0 } +```rust +use std::thread::Thread; + +fn generate_thread_number() -> i32 { 4 } // a very simple generation + // Generate some state locally let child_thread_number = generate_thread_number(); -spawn(move || { +Thread::spawn(move || { // Capture it in the remote thread. The `move` keyword indicates // that this closure should move `child_thread_number` into its // environment, rather than capturing a reference into the @@ -77,20 +79,22 @@ The simplest way to create a channel is to use the `channel` function to create of a channel, and a *receiver* is the receiving endpoint. Consider the following example of calculating two results concurrently: -```{rust,ignore} -# use std::thread::spawn; +```rust +use std::thread::Thread; +use std::sync::mpsc; -let (tx, rx): (Sender, Receiver) = channel(); +let (tx, rx): (mpsc::Sender, mpsc::Receiver) = mpsc::channel(); -spawn(move || { +Thread::spawn(move || { let result = some_expensive_computation(); tx.send(result); }); some_other_expensive_computation(); let result = rx.recv(); -# fn some_expensive_computation() -> int { 42 } -# fn some_other_expensive_computation() {} + +fn some_expensive_computation() -> u32 { 42 } // very expensive ;) +fn some_other_expensive_computation() {} // even more so ``` Let's examine this example in detail. First, the `let` statement creates a @@ -98,19 +102,21 @@ stream for sending and receiving integers (the left-hand side of the `let`, `(tx, rx)`, is an example of a destructuring let: the pattern separates a tuple into its component parts). -```{rust,ignore} -let (tx, rx): (Sender, Receiver) = channel(); +```rust +# use std::sync::mpsc; +let (tx, rx): (mpsc::Sender, mpsc::Receiver) = mpsc::channel(); ``` The child thread will use the sender to send data to the parent thread, which will wait to receive the data on the receiver. The next statement spawns the child thread. -```{rust,ignore} -# use std::thread::spawn; -# fn some_expensive_computation() -> int { 42 } -# let (tx, rx) = channel(); -spawn(move || { +```rust +# use std::thread::Thread; +# use std::sync::mpsc; +# fn some_expensive_computation() -> u32 { 42 } +# let (tx, rx) = mpsc::channel(); +Thread::spawn(move || { let result = some_expensive_computation(); tx.send(result); }); @@ -125,9 +131,10 @@ computation, then sends the result over the captured channel. Finally, the parent continues with some other expensive computation, then waits for the child's result to arrive on the receiver: -```{rust,ignore} +```rust +# use std::sync::mpsc; # fn some_other_expensive_computation() {} -# let (tx, rx) = channel::(); +# let (tx, rx) = mpsc::channel::(); # tx.send(0); some_other_expensive_computation(); let result = rx.recv(); @@ -140,8 +147,9 @@ single `Receiver` value. What if our example needed to compute multiple results across a number of threads? The following program is ill-typed: ```{rust,ignore} -# fn some_expensive_computation() -> int { 42 } -let (tx, rx) = channel(); +# use std::sync::mpsc; +# fn some_expensive_computation() -> u32 { 42 } +let (tx, rx) = mpsc::channel(); spawn(move || { tx.send(some_expensive_computation()); @@ -156,19 +164,22 @@ spawn(move || { Instead we can clone the `tx`, which allows for multiple senders. -```{rust,ignore} -let (tx, rx) = channel(); +```rust +use std::thread::Thread; +use std::sync::mpsc; -for init_val in range(0u, 3) { +let (tx, rx) = mpsc::channel(); + +for init_val in 0 .. 3 { // Create a new channel handle to distribute to the child thread let child_tx = tx.clone(); - spawn(move || { + Thread::spawn(move || { child_tx.send(some_expensive_computation(init_val)); }); } -let result = rx.recv() + rx.recv() + rx.recv(); -# fn some_expensive_computation(_i: uint) -> int { 42 } +let result = rx.recv().unwrap() + rx.recv().unwrap() + rx.recv().unwrap(); +# fn some_expensive_computation(_i: u32) -> u32 { 42 } ``` Cloning a `Sender` produces a new handle to the same channel, allowing multiple @@ -181,21 +192,22 @@ Note that the above cloning example is somewhat contrived since you could also simply use three `Sender` pairs, but it serves to illustrate the point. For reference, written with multiple streams, it might look like the example below. -```{rust,ignore} -# use std::thread::spawn; +```rust +use std::thread::Thread; +use std::sync::mpsc; // Create a vector of ports, one for each child thread -let rxs = Vec::from_fn(3, |init_val| { - let (tx, rx) = channel(); - spawn(move || { +let rxs = (0 .. 3).map(|&:init_val| { + let (tx, rx) = mpsc::channel(); + Thread::spawn(move || { tx.send(some_expensive_computation(init_val)); }); rx -}); +}).collect::>(); // Wait on each port, accumulating the results -let result = rxs.iter().fold(0, |accum, rx| accum + rx.recv() ); -# fn some_expensive_computation(_i: uint) -> int { 42 } +let result = rxs.iter().fold(0, |&:accum, rx| accum + rx.recv().unwrap() ); +# fn some_expensive_computation(_i: u32) -> u32 { 42 } ``` ## Backgrounding computations: Futures diff --git a/src/libcore/cell.rs b/src/libcore/cell.rs index ec4007c4c6d..963cb48db07 100644 --- a/src/libcore/cell.rs +++ b/src/libcore/cell.rs @@ -115,7 +115,6 @@ //! } //! # fn calc_span_tree(&self) -> Vec<(uint, uint)> { vec![] } //! } -//! # fn main() { } //! ``` //! //! ## Mutating implementations of `clone` diff --git a/src/libcore/finally.rs b/src/libcore/finally.rs index 4c2a2ff1086..ed3612bded0 100644 --- a/src/libcore/finally.rs +++ b/src/libcore/finally.rs @@ -23,13 +23,11 @@ //! //! use std::finally::Finally; //! -//! # fn main() { //! (|&mut:| { //! // ... //! }).finally(|| { //! // this code is always run //! }) -//! # } //! ``` #![deprecated = "It is unclear if this module is more robust than implementing \ diff --git a/src/libcore/macros.rs b/src/libcore/macros.rs index 3d3b9f8cf65..1c37126e8e9 100644 --- a/src/libcore/macros.rs +++ b/src/libcore/macros.rs @@ -39,13 +39,16 @@ macro_rules! panic { /// // the panic message for these assertions is the stringified value of the /// // expression given. /// assert!(true); -/// # fn some_computation() -> bool { true } +/// +/// fn some_computation() -> bool { true } // a very simple function +/// /// assert!(some_computation()); /// /// // assert with a custom message -/// # let x = true; +/// let x = true; /// assert!(x, "x wasn't true!"); -/// # let a = 3i; let b = 27i; +/// +/// let a = 3i; let b = 27i; /// assert!(a + b == 30, "a = {}, b = {}", a, b); /// ``` #[macro_export] @@ -108,13 +111,15 @@ macro_rules! assert_eq { /// // the panic message for these assertions is the stringified value of the /// // expression given. /// debug_assert!(true); -/// # fn some_expensive_computation() -> bool { true } +/// +/// fn some_expensive_computation() -> bool { true } // a very simple function /// debug_assert!(some_expensive_computation()); /// /// // assert with a custom message -/// # let x = true; +/// let x = true; /// debug_assert!(x, "x wasn't true!"); -/// # let a = 3i; let b = 27i; +/// +/// let a = 3; let b = 27; /// debug_assert!(a + b == 30, "a = {}, b = {}", a, b); /// ``` #[macro_export] diff --git a/src/libcore/marker.rs b/src/libcore/marker.rs index 715a79abe85..6d272f91698 100644 --- a/src/libcore/marker.rs +++ b/src/libcore/marker.rs @@ -210,8 +210,7 @@ impl Clone for ContravariantType { /// "interior" mutability: /// /// ``` -/// pub struct Cell { value: T } -/// # fn main() {} +/// struct Cell { value: T } /// ``` /// /// The type system would infer that `value` is only read here and diff --git a/src/libcore/prelude.rs b/src/libcore/prelude.rs index c3bb9c91557..da3f180d7e1 100644 --- a/src/libcore/prelude.rs +++ b/src/libcore/prelude.rs @@ -21,11 +21,7 @@ //! # Example //! //! ```ignore -//! # fn main() { -//! #![feature(globs)] -//! //! use core::prelude::*; -//! # } //! ``` // Reexported core operators diff --git a/src/libcore/result.rs b/src/libcore/result.rs index 110bce5c124..1ab810f937d 100644 --- a/src/libcore/result.rs +++ b/src/libcore/result.rs @@ -217,11 +217,9 @@ //! makes it clear: //! //! ``` -//! # #![feature(macro_rules)] //! macro_rules! try { //! ($e:expr) => (match $e { Ok(e) => e, Err(e) => return Err(e) }) //! } -//! # fn main() { } //! ``` //! //! `try!` is imported by the prelude, and is available everywhere. diff --git a/src/libstd/fmt.rs b/src/libstd/fmt.rs index 907925e93d3..36afa0956d2 100644 --- a/src/libstd/fmt.rs +++ b/src/libstd/fmt.rs @@ -26,15 +26,13 @@ //! //! Some examples of the `format!` extension are: //! -//! ```rust -//! # fn main() { +//! ``` //! format!("Hello"); // => "Hello" //! format!("Hello, {}!", "world"); // => "Hello, world!" //! format!("The number is {}", 1i); // => "The number is 1" //! format!("{:?}", (3i, 4i)); // => "(3i, 4i)" //! format!("{value}", value=4i); // => "4" //! format!("{} {}", 1i, 2u); // => "1 2" -//! # } //! ``` //! //! From these, you can see that the first argument is a format string. It is @@ -83,12 +81,10 @@ //! //! For example, the following `format!` expressions all use named argument: //! -//! ```rust -//! # fn main() { +//! ``` //! format!("{argument}", argument = "test"); // => "test" //! format!("{name} {}", 1i, name = 2i); // => "2 1" //! format!("{a} {c} {b}", a="a", b='b', c=3i); // => "a 3 b" -//! # } //! ``` //! //! It is illegal to put positional parameters (those without names) after @@ -288,8 +284,6 @@ //! use std::fmt; //! use std::io; //! -//! # #[allow(unused_must_use)] -//! # fn main() { //! fmt::format(format_args!("this returns {}", "String")); //! //! let some_writer: &mut io::Writer = &mut io::stdout(); @@ -299,7 +293,6 @@ //! write!(&mut io::stdout(), "{}", args); //! } //! my_fmt_fn(format_args!("or a {} too", "function")); -//! # } //! ``` //! //! The result of the `format_args!` macro is a value of type `fmt::Arguments`. diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index bab4dafd090..e2b71cd43af 100644 --- a/src/libstd/io/mod.rs +++ b/src/libstd/io/mod.rs @@ -934,16 +934,15 @@ unsafe fn slice_vec_capacity<'a, T>(v: &'a mut Vec, start: uint, end: uint) - /// A `RefReader` is a struct implementing `Reader` which contains a reference /// to another reader. This is often useful when composing streams. /// -/// # Example +/// # Examples /// /// ``` -/// # fn main() {} -/// # fn process_input(r: R) {} -/// # fn foo() { /// use std::io; /// use std::io::ByRefReader; /// use std::io::util::LimitReader; /// +/// fn process_input(r: R) {} +/// /// let mut stream = io::stdin(); /// /// // Only allow the function to process at most one kilobyte of input @@ -953,8 +952,6 @@ unsafe fn slice_vec_capacity<'a, T>(v: &'a mut Vec, start: uint, end: uint) - /// } /// /// // 'stream' is still available for use here -/// -/// # } /// ``` pub struct RefReader<'a, R:'a> { /// The underlying reader which this is referencing @@ -1269,12 +1266,11 @@ impl<'a> Writer for &'a mut (Writer+'a) { /// # Example /// /// ``` -/// # fn main() {} -/// # fn process_input(r: R) {} -/// # fn foo () { /// use std::io::util::TeeReader; /// use std::io::{stdin, ByRefWriter}; /// +/// fn process_input(r: R) {} +/// /// let mut output = Vec::new(); /// /// { @@ -1285,7 +1281,6 @@ impl<'a> Writer for &'a mut (Writer+'a) { /// } /// /// println!("input processed: {:?}", output); -/// # } /// ``` pub struct RefWriter<'a, W:'a> { /// The underlying writer which this is referencing @@ -1705,19 +1700,19 @@ pub enum FileType { /// A structure used to describe metadata information about a file. This /// structure is created through the `stat` method on a `Path`. /// -/// # Example +/// # Examples +/// +/// ```no_run +/// # #![allow(unstable)] +/// +/// use std::io::fs::PathExtensions; /// -/// ``` -/// # use std::io::fs::PathExtensions; -/// # fn main() {} -/// # fn foo() { /// let info = match Path::new("foo.txt").stat() { /// Ok(stat) => stat, /// Err(e) => panic!("couldn't read foo.txt: {}", e), /// }; /// /// println!("byte size: {}", info.size); -/// # } /// ``` #[derive(Copy, Hash)] pub struct FileStat { diff --git a/src/libstd/io/net/pipe.rs b/src/libstd/io/net/pipe.rs index 42d9fff6d15..61d164d21e3 100644 --- a/src/libstd/io/net/pipe.rs +++ b/src/libstd/io/net/pipe.rs @@ -168,9 +168,7 @@ impl UnixListener { /// # Example /// /// ``` - /// # fn main() {} /// # fn foo() { - /// # #![allow(unused_must_use)] /// use std::io::net::pipe::UnixListener; /// use std::io::{Listener, Acceptor}; /// diff --git a/src/libstd/io/net/tcp.rs b/src/libstd/io/net/tcp.rs index 6a3f5fcb2c6..4978085fa4f 100644 --- a/src/libstd/io/net/tcp.rs +++ b/src/libstd/io/net/tcp.rs @@ -272,12 +272,10 @@ impl sys_common::AsInner for TcpStream { /// A structure representing a socket server. This listener is used to create a /// `TcpAcceptor` which can be used to accept sockets on a local port. /// -/// # Example +/// # Examples /// -/// ```rust -/// # fn main() { } +/// ``` /// # fn foo() { -/// # #![allow(dead_code)] /// use std::io::{TcpListener, TcpStream}; /// use std::io::{Acceptor, Listener}; /// use std::thread::Thread; diff --git a/src/libstd/io/timer.rs b/src/libstd/io/timer.rs index 8a0445be471..844a97dea2d 100644 --- a/src/libstd/io/timer.rs +++ b/src/libstd/io/timer.rs @@ -27,10 +27,9 @@ use sys::timer::Timer as TimerImp; /// period of time. Handles to this timer can also be created in the form of /// receivers which will receive notifications over time. /// -/// # Example +/// # Examples /// /// ``` -/// # fn main() {} /// # fn foo() { /// use std::io::Timer; /// use std::time::Duration; @@ -54,7 +53,6 @@ use sys::timer::Timer as TimerImp; /// the `io::timer` module. /// /// ``` -/// # fn main() {} /// # fn foo() { /// use std::io::timer; /// use std::time::Duration; diff --git a/src/libstd/macros.rs b/src/libstd/macros.rs index a420c841d25..5795b4c38c6 100644 --- a/src/libstd/macros.rs +++ b/src/libstd/macros.rs @@ -122,16 +122,18 @@ macro_rules! try { /// receivers. It places no restrictions on the types of receivers given to /// this macro, this can be viewed as a heterogeneous select. /// -/// # Example +/// # Examples /// /// ``` /// use std::thread::Thread; -/// use std::sync::mpsc::channel; +/// use std::sync::mpsc; /// -/// let (tx1, rx1) = channel(); -/// let (tx2, rx2) = channel(); -/// # fn long_running_task() {} -/// # fn calculate_the_answer() -> int { 42i } +/// // two placeholder functions for now +/// fn long_running_task() {} +/// fn calculate_the_answer() -> u32 { 42 } +/// +/// let (tx1, rx1) = mpsc::channel(); +/// let (tx2, rx2) = mpsc::channel(); /// /// Thread::spawn(move|| { long_running_task(); tx1.send(()).unwrap(); }); /// Thread::spawn(move|| { tx2.send(calculate_the_answer()).unwrap(); }); @@ -251,17 +253,15 @@ pub mod builtin { /// statement or expression position, meaning this macro may be difficult to /// use in some situations. /// - /// # Example + /// # Examples /// /// ``` /// #![feature(concat_idents)] /// - /// # fn main() { - /// fn foobar() -> int { 23 } + /// fn foobar() -> u32 { 23 } /// /// let f = concat_idents!(foo, bar); /// println!("{}", f()); - /// # } /// ``` #[macro_export] macro_rules! concat_idents { diff --git a/src/libstd/sync/future.rs b/src/libstd/sync/future.rs index 568c24446e7..36bbc5ff5b4 100644 --- a/src/libstd/sync/future.rs +++ b/src/libstd/sync/future.rs @@ -11,14 +11,18 @@ //! A type representing values that may be computed concurrently and operations //! for working with them. //! -//! # Example +//! # Examples //! -//! ```rust +//! ``` //! use std::sync::Future; -//! # fn fib(n: uint) -> uint {42}; -//! # fn make_a_sandwich() {}; -//! let mut delayed_fib = Future::spawn(move|| { fib(5000) }); -//! make_a_sandwich(); +//! +//! // a fake, for now +//! fn fib(n: u32) -> u32 { 42 }; +//! +//! let mut delayed_fib = Future::spawn(move || fib(5000)); +//! +//! // do stuff... +//! //! println!("fib(5000) = {}", delayed_fib.get()) //! ```