Add some documentation

src/lib.rs

@@ -1,5 +1,6 @@
 #![feature(macro_rules)]
 #![feature(unsafe_destructor)]
+#![unstable]
 
 #[cfg(all(not(windows), not(unix)))]
 use this_platform_is_not_supported;
@@ -11,15 +12,17 @@ mod samples_formats;
 
 #[cfg(unix)]
 #[path="alsa/mod.rs"]
-pub mod cpal_impl;
+mod cpal_impl;
 #[cfg(windows)]
 #[path="wasapi/mod.rs"]
-pub mod cpal_impl;
+mod cpal_impl;
 
-/// A `Channel` represents a sound output.
+/// Controls a sound output.
 ///
-/// A channel must be periodically filled with new data, or the sound will
-/// stop playing.
+/// Create one `Channel` for each sound that you want to play.
+///
+/// A channel must be periodically filled with new data by calling `append_data`, or the sound
+/// will stop playing.
 pub struct Channel(cpal_impl::Channel);
 
 /// Number of channels.
@@ -50,6 +53,7 @@ struct RequiredConversion<T> {
 }
 
 impl Channel {
+    /// Builds a new channel.
     pub fn new() -> Channel {
         let channel = cpal_impl::Channel::new();
         Channel(channel)

src/samples_formats.rs

@@ -8,10 +8,12 @@ pub enum SampleFormat {
     I16,
     /// The value 0 corresponds to 32768.
     U16,
+    /// The boundaries are (-1.0, 1.0).
     F32,
 }
 
 impl SampleFormat {
+    /// Returns the size in bytes of a sample of this format.
     pub fn get_sample_size(&self) -> uint {
         match self {
             &SampleFormat::I16 => mem::size_of::<i16>(),
@@ -26,11 +28,11 @@ impl SampleFormat {
 pub trait Sample: Copy {
     fn get_format(Option<Self>) -> SampleFormat;
 
-    /// Turns the data into a `Vec<i16>` where each element is a sample.
+    /// Turns the data into samples of type `I16`.
     fn to_vec_i16(&[Self]) -> Cow<Vec<i16>, [i16]>;
-    /// Turns the data into a `Vec<u16>` where each element is a sample.
+    /// Turns the data into samples of type `U16`.
     fn to_vec_u16(&[Self]) -> Cow<Vec<u16>, [u16]>;
-    /// Turns the data into a `Vec<f32>` where each element is a sample.
+    /// Turns the data into samples of type `F32`.
     fn to_vec_f32(&[Self]) -> Cow<Vec<f32>, [f32]>;
 }