More documentation rework

.travis.yml

@@ -16,15 +16,7 @@ addons:
     packages:
     - libasound2-dev
 
-after_success: 
-    - |
-        [ $TRAVIS_BRANCH = master ] &&
-        [ $TRAVIS_PULL_REQUEST = false ] &&
-        [ $TRAVIS_RUST_VERSION = nightly ] &&
-        cargo doc &&
-        git clone https://github.com/davisp/ghp-import &&
-        ./ghp-import/ghp-import target/doc &&
-        git push -fq https://${GH_TOKEN}@github.com/${TRAVIS_REPO_SLUG}.git gh-pages
+after_success:
     - |
         [ $TRAVIS_BRANCH = master ] &&
         [ $TRAVIS_PULL_REQUEST = false ] &&

Cargo.toml

@@ -6,7 +6,7 @@ license = "Apache-2.0"
 description = "Audio playback library"
 keywords = ["audio", "playback", "gamedev"]
 repository = "https://github.com/tomaka/rodio"
-documentation = "http://tomaka.github.io/rodio/rodio/index.html"
+documentation = "http://docs.rs/rodio"
 
 [dependencies]
 cpal = "0.4.0"

README.md

@@ -1,7 +1,6 @@
 # Audio playback library
 
 [![Build Status](https://travis-ci.org/tomaka/rodio.svg?branch=master)](https://travis-ci.org/tomaka/rodio)
-
 [![](http://meritbadge.herokuapp.com/rodio)](https://crates.io/crates/rodio)
 
 Rust playback library.
@@ -10,6 +9,6 @@ Rust playback library.
  - WAV decoding is handled by [hound](https://github.com/ruud-v-a/hound).
  - Vorbis decoding is handled by [lewton](https://github.com/est31/lewton).
 
-## [Documentation](http://tomaka.github.io/rodio/rodio/index.html)
+# [Documentation](http://docs.rs/rodio)
 
-See the documentation for usage.
+[The documentation](http://docs.rs/rodio) contains an introduction to the library.

src/conversions/sample.rs

@@ -52,8 +52,19 @@ impl<I, O> ExactSizeIterator for DataConverter<I, O>
 {
 }
 
-
 /// Represents a value of a single sample.
+///
+/// This trait is implemented by default on three types: `i16`, `u16` and `f32`.
+///
+/// - For `i16`, silence corresponds to the value `0`. The minimum and maximum amplitudes are
+///   represented by `i16::min_value()` and `i16::max_value()` respectively.
+/// - For `u16`, silence corresponds to the value `u16::max_value() / 2`. The minimum and maximum
+///   amplitudes are represented by `0` and `u16::max_value()` respectively.
+/// - For `f32`, silence corresponds to the value `0.0`. The minimum and maximum amplitudes are
+///  represented by `-1.0` and `1.0` respectively.
+///
+/// You can implement this trait on your own type as well if you wish so.
+///
 pub trait Sample: cpal::Sample + Add + AddAssign {
     /// Linear interpolation between two samples.
     ///

src/decoder/mod.rs

@@ -1,3 +1,5 @@
+//! Decodes samples from an audio file.
+
 use std::error::Error;
 use std::fmt;
 use std::io::{Read, Seek};

src/lib.rs

@@ -1,55 +1,81 @@
-//! # Usage
+//! Audio playback library.
 //!
-//! There are two main concepts in this library:
+//! The main concept of this library is [the `Source` trait](source/trait.Source.html), which
+//! represents a sound (streaming or not). In order to play a sound, there are three steps:
 //!
-//! - Sources, represented with [the `Source` trait](source/trait.Source.html), that provide sound
-//!   data.
-//! - Sinks, which accept sound data.
+//! - Create an object that represents the streaming sound. It can be a sine wave, a buffer, a
+//!   [decoder](decoder/index.html), etc. or even your own type that implements
+//!   [the `Source` trait](source/trait.Source.html).
+//! - Choose an output which the [`get_endpoints_list`](fn.get_endpoints_list.html) or
+//!   [`get_default_endpoint`](fn.get_default_endpoint.html) functions.
+//! - Call [`play_raw(output, source)`](fn.play_raw.html).
 //!
-//! > **Note**: If you are not familiar with what a sound is or how a sound is stored in memory,
-//! > check out the documentation of [the `Source` trait](source/trait.Source.html).
-//!
-//! In order to play a sound, you need to create a source, a sink, and connect the two. For example
-//! here is how you play a sound file:
+//! For example, here is how you would play an audio file:
 //!
 //! ```no_run
+//! use std::fs::File;
 //! use std::io::BufReader;
 //!
 //! let endpoint = rodio::get_default_endpoint().unwrap();
-//! let sink = rodio::Sink::new(&endpoint);
 //!
-//! let file = std::fs::File::open("music.ogg").unwrap();
+//! let file = File::open("sound.ogg").unwrap();
 //! let source = rodio::Decoder::new(BufReader::new(file)).unwrap();
+//! rodio::play_raw(&endpoint, source);
+//! ```
+//!
+//! ## Sink
+//!
+//! In order to make it easier to control the playback, the rodio library also provides a type
+//! named [`Sink`](struct.Sink.html) which represents an audio track.
+//!
+//! Instead of playing the sound with [`play_raw`](fn.play_raw.html), you can add it to a
+//! [`Sink`](struct.Sink.html) instead.
+//!
+//! ```no_run
+//! use rodio::Sink;
+//!
+//! let endpoint = rodio::get_default_endpoint().unwrap();
+//! let sink = Sink::new(&endpoint);
+//!
+//! // Add a dummy source of the sake of the example.
+//! let source = rodio::source::SineWave::new(440);
 //! sink.append(source);
 //! ```
 //!
-//! The `append` method takes ownership of the source and starts playing it. If a sink is already
-//! playing a sound when you call `append`, the sound is added to a queue and will start playing
-//! when the existing source is over.
+//! The [`append` method](struct.Sink.html#method.append) will add the sound at the end of the
+//! sink. It will be played when all the previous sounds have been played. If you want multiple
+//! sounds to play simultaneously, you should create multiple [`Sink`](struct.Sink.html)s.
 //!
-//! If you want to play multiple sounds simultaneously, you should create multiple sinks.
+//! The [`Sink`](struct.Sink.html) type also provides utilities such as playing/pausing or
+//! controlling the volume.
 //!
-//! # How it works
+//! ## Filters
 //!
-//! Rodio spawns a background thread that is dedicated to reading from the sources and sending
-//! the output to the endpoint.
-//!
-//! All the sounds are mixed together by rodio before being sent. Since this is handled by the
-//! software, there is no restriction for the number of sinks that can be created.
-//!
-//! # Adding effects
-//!
-//! The `Source` trait provides various filters, similarly to the standard `Iterator` trait.
+//! [The `Source` trait](source/trait.Source.html) provides various filters, similarly to the
+//! standard `Iterator` trait.
 //!
 //! Example:
 //!
-//! ```ignore
+//! ```
 //! use rodio::Source;
 //! use std::time::Duration;
 //!
-//! // repeats the first five seconds of this sound forever
+//! // Repeats the first five seconds of the sound forever.
+//! # let source = rodio::source::SineWave::new(440);
 //! let source = source.take_duration(Duration::from_secs(5)).repeat_infinite();
 //! ```
+//!
+//! ## How it works under the hood
+//!
+//! Rodio spawns a background thread that is dedicated to reading from the sources and sending
+//! the output to the endpoint. Whenever you give up ownership of a `Source` in order to play it,
+//! it is sent to this background thread where it will be read by rodio.
+//!
+//! All the sounds are mixed together by rodio before being sent to the operating system or the
+//! hardware. Therefore there is no restriction on the number of sounds that play simultaneously or
+//! the number of sinks that can be created (except for the fact that creating too many will slow
+//! down your program).
+//!
 
 #![cfg_attr(test, deny(missing_docs))]
 

src/source/mod.rs

@@ -1,3 +1,5 @@
+//! Sources of sound and various filters.
+
 use std::time::Duration;
 
 use Sample;