Add some documentation

README.md

@@ -1,3 +1,5 @@
 # CPAL - Cross-platform audio library
 
 Audio player in pure Rust.
+
+ * Works only on win32 for the moment

examples/basic.rs

@@ -3,6 +3,7 @@ extern crate cpal;
 fn main() {
     let mut channel = cpal::Channel::new();
 
+    // producing a sinusoid
     let mut data_source =
         std::iter::iterate(0.0f32, |f| f + 0.03)
             .map(|angle| {

src/lib.rs

@@ -7,8 +7,15 @@ use this_platform_is_not_supported;
 #[path="wasapi/mod.rs"]
 pub mod cpal_impl;
 
+/// A `Channel` represents a sound output.
+///
+/// A channel must be periodically filled with new data, or the sound will
+/// stop playing.
 pub struct Channel(cpal_impl::Channel);
 
+/// Represents a buffer that must be filled with audio data.
+///
+/// A `Buffer` object borrows the channel.
 pub struct Buffer<'a, T>(cpal_impl::Buffer<'a, T>);
 
 impl Channel {
@@ -17,10 +24,18 @@ impl Channel {
         Channel(channel)
     }
 
+    /// Returns the number of channels.
+    ///
+    /// 1 for mono, 2 for stereo, etc.
     pub fn get_channels(&self) -> u16 {
         self.0.get_channels()
     }
 
+    /// Adds some PCM data to the channel's buffer.
+    ///
+    /// This function returns a `Buffer` object that must be filled with the audio data.
+    /// You can't know in advance the size of the buffer, as it depends on the current state
+    /// of the backend.
     pub fn append_data<'a, T>(&'a mut self) -> Buffer<'a, T> {
         Buffer(self.0.append_data())
     }