Add docs to lib.rs

src/lib.rs

@@ -1,5 +1,6 @@
 #![feature(unsafe_destructor)]
 #![feature(globs)]
+#![unstable]
 
 extern crate libc;
 
@@ -26,7 +27,63 @@ pub struct Window {
     nosend: std::kinds::marker::NoSend,
 }
 
+/// Represents an OpenGL context and the Window or environment around it.
+///
+/// # Example
+///
+/// ```
+/// use std::default::Default;
+/// 
+/// let window = Window::new(None, "Hello world!", &Default::default(), None).unwrap();
+/// 
+/// window.make_current();
+/// 
+/// loop {
+///     for event in window.poll_events().move_iter() {     // note: this may change in the future
+///         match event {
+///             // process events here
+///             _ => ()
+///         }
+///     }
+///     
+///     // draw everything here
+///
+///     window.swap_buffers();
+///     std::io::timer::sleep(17);
+/// }
+/// 
+/// while !window.is_closed() {
+///  println!("{}", window.wait_events());
+/// 
+/// gl::Clear(gl::COLOR_BUFFER_BIT);
+/// 
+/// window.swap_buffers();
+/// }
 impl Window {
+    /// Creates a new OpenGL context, and a Window for platforms where this is appropriate.
+    /// 
+    /// # Parameters
+    /// 
+    /// The `dimensions` parameter tell the library what the dimensions of the client area
+    ///  of the window must be. If set to `None`, the library will choose or let the O/S choose.
+    ///
+    /// The `title` parameter is the title that the window must have.
+    ///
+    /// The `hints` parameter must be a `Hint` object which contains hints about how the context
+    ///  must be created. This library will *try* to follow the hints, but will still success
+    ///  even if it could not conform to all of them.
+    ///
+    /// The `monitor` parameter is the identifier of the monitor that this window should fill.
+    ///  If `None`, a windowed window will be created. If `Some(_)`, the window will be fullscreen
+    ///  and will fill the given monitor. Note `MonitorID` does not necessarly represent a
+    ///  *physical* monitor.
+    ///
+    /// # Return value
+    ///
+    /// Returns the `Window` object.
+    ///
+    /// Error should be very rare and only occur in case of permission denied, incompatible system,
+    ///  out of memory, etc.
     #[inline]
     pub fn new(dimensions: Option<(uint, uint)>, title: &str,
         hints: &Hints, monitor: Option<MonitorID>)
@@ -39,13 +96,13 @@ impl Window {
         })
     }
 
-    /// Returns true if the window has been closed by the user.
+    /// Returns true if the window has previously been closed by the user.
     #[inline]
     pub fn is_closed(&self) -> bool {
         self.window.is_closed()
     }
 
-    /// Returns true if the window has been closed by the user.
+    /// Returns true if the window has previously been closed by the user.
     #[inline]
     #[deprecated = "Use is_closed instead"]
     pub fn should_close(&self) -> bool {
@@ -53,12 +110,22 @@ impl Window {
     }
 
     /// Modifies the title of the window.
+    ///
+    /// This is a no-op if the window has already been closed.
     #[inline]
     pub fn set_title(&self, title: &str) {
         self.window.set_title(title)
     }
 
-    /// Returns the position of the window relative to the top-left hand corner of the screen.
+    /// Returns the position of the top-left hand corner of the window relative to the
+    ///  top-left hand corner of the desktop.
+    ///
+    /// Note that the top-left hand corner of the desktop is not necessarly the same as
+    ///  the screen. If the user uses a desktop with multiple monitors, the top-left hand corner
+    ///  of the desktop is the top-left hand corner of the monitor at the top-left of the desktop.
+    ///
+    /// The coordinates can be negative if the top-left hand corner of the window is outside
+    ///  of the visible screen region.
     ///
     /// Returns `None` if the window no longer exists.
     #[inline]
@@ -66,48 +133,95 @@ impl Window {
         self.window.get_position()
     }
 
+    /// Modifies the position of the window.
+    ///
+    /// See `get_position` for more informations about the coordinates.
+    ///
+    /// This is a no-op if the window has already been closed.
     #[inline]
     pub fn set_position(&self, x: uint, y: uint) {
         self.window.set_position(x, y)
     }
 
+    /// Returns the size in pixels of the client area of the window.
+    ///
+    /// The client area is the content of the window, excluding the title bar and borders.
+    /// These are the dimensions of the frame buffer, and the dimensions that you should use
+    ///  when you call `glViewport`.
+    ///
+    /// Returns `None` if the window no longer exists.
     #[inline]
     pub fn get_inner_size(&self) -> Option<(uint, uint)> {
         self.window.get_inner_size()
     }
 
+    /// Returns the size in pixels of the window.
+    ///
+    /// These dimensions include title bar and borders. If you don't want these, you should use
+    ///  use `get_inner_size` instead.
+    ///
+    /// Returns `None` if the window no longer exists.
     #[inline]
     pub fn get_outer_size(&self) -> Option<(uint, uint)> {
         self.window.get_outer_size()
     }
 
+    /// Modifies the inner size of the window.
+    ///
+    /// See `get_inner_size` for more informations about the values.
+    ///
+    /// This is a no-op if the window has already been closed.
     #[inline]
     pub fn set_inner_size(&self, x: uint, y: uint) {
         self.window.set_inner_size(x, y)
     }
 
-    // TODO: return iterator
+    /// Returns all the events that are currently in window's events queue.
+    /// 
+    /// Contrary to `wait_events`, this function never blocks.
+    #[experimental = "Will probably be changed to return an iterator instead of a Vec"]
     #[inline]
     pub fn poll_events(&self) -> Vec<Event> {
         self.window.poll_events()
     }
 
-    // TODO: return iterator
+    /// Returns all the events that are currently in window's events queue.
+    /// If there are no events in queue, this function will block until there is one.
+    ///
+    /// This is equivalent to:
+    ///
+    /// ```
+    /// loop {
+    ///     let events = poll_events();
+    ///     if events.len() >= 1 { return events }
+    /// }
+    /// ```
+    ///
+    /// ...but without the spinlock.
     #[inline]
+    #[experimental = "Will probably be changed to return an iterator instead of a Vec"]
     pub fn wait_events(&self) -> Vec<Event> {
         self.window.wait_events()
     }
 
     #[inline]
+    #[experimental]
     pub fn make_current(&self) {
         self.window.make_current()
     }
 
+    /// Returns the address of an OpenGL function.
+    ///
+    /// Contrary to `wglGetProcAddress`, all available OpenGL functions return an address.
     #[inline]
     pub fn get_proc_address(&self, addr: &str) -> *const () {
         self.window.get_proc_address(addr)
     }
 
+    /// Swaps the buffers in case of double or triple buffering.
+    ///
+    /// You should call this function every time you have finished rendering, or the image
+    ///  may not be displayed on the screen.
     #[inline]
     pub fn swap_buffers(&self) {
         self.window.swap_buffers()