docs: updates the docs and copyright notices for 1.0 by adding exampl…

…es sections

src/lib.rs

@@ -1,3 +1,12 @@
+// Copyright ⓒ 2015-2017 Benjamin Sago, Kevin Knapp, and [`term_size` contributors.](https://github.com/kbknapp/term_size-rs/blob/master/CONTRIBUTORS.md).
+// 
+// Licensed under either of
+// 
+// * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+// * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+// 
+// at your option. Unless specifically stated otherwise, all contributions will be licensed in the same manner.
+
 // The following was originally taken and adapated from exa source
 // repo: https://github.com/ogham/exa
 // commit: b9eb364823d0d4f9085eb220233c704a13d0f611
@@ -11,6 +20,31 @@
 //!
 //! The size is needed when the user wants the output formatted into columns:
 //! the default grid view, or the hybrid grid-details view.
+//! 
+//! # Example
+//! 
+//! To get the dimensions of your terminal window, simply use the following:
+//! 
+//! ```no_run
+//! # use term_size;
+//! if let Some((w, h)) = term_size::dimensions() {
+//!     println!("Width: {}\nHeight: {}", w, h);
+//! } else {
+//!     println!("Unable to get term size :(")
+//! }
+//! ```
+#![doc(html_root_url = "https://docs.rs/term_size/1.0.0-beta1")]
+#![deny(missing_docs, 
+        missing_debug_implementations, 
+        missing_copy_implementations, 
+        trivial_casts,
+        unused_import_braces, 
+        unused_allocation,
+        unused_qualifications,
+        trivial_numeric_casts)]
+#![cfg_attr(not(any(feature = "lints", feature = "nightly")), forbid(unstable_features))]
+#![cfg_attr(feature = "lints", feature(plugin))]
+#![cfg_attr(feature = "lints", plugin(clippy))]
 
 #[cfg(not(target_os = "windows"))]
 extern crate libc;

src/platform/unix.rs

@@ -86,7 +86,22 @@ unsafe fn get_dimensions_err() -> winsize {
 /// that order, in the attempt to dtermine terminal width. If one of those streams is actually
 /// a tty, this function returns its width and height as a number of characters.
 ///
+/// # Errors
+/// 
 /// If *all* of the streams are not ttys or return any errors this function will return `None`.
+/// 
+/// # Example
+/// 
+/// To get the dimensions of your terminal window, simply use the following:
+/// 
+/// ```no_run
+/// # use term_size;
+/// if let Some((w, h)) = term_size::dimensions() {
+///     println!("Width: {}\nHeight: {}", w, h);
+/// } else {
+///     println!("Unable to get term size :(")
+/// }
+/// ```
 pub fn dimensions() -> Option<(usize, usize)> {
     let w = unsafe { get_dimensions_any() };
 
@@ -101,7 +116,22 @@ pub fn dimensions() -> Option<(usize, usize)> {
 /// terminal width. If that streams is actually a tty, this function returns its width
 /// and height as a number of characters.
 ///
-/// If *all* of the streams are not ttys or return any errors this function will return `None`.
+/// # Errors
+/// 
+/// If the stream is not a tty or return any errors this function will return `None`.
+/// 
+/// # Example
+/// 
+/// To get the dimensions of your terminal window, simply use the following:
+/// 
+/// ```no_run
+/// # use term_size;
+/// if let Some((w, h)) = term_size::dimensions_stdout() {
+///     println!("Width: {}\nHeight: {}", w, h);
+/// } else {
+///     println!("Unable to get term size :(")
+/// }
+/// ```
 pub fn dimensions_stdout() -> Option<(usize, usize)> {
     let w = unsafe { get_dimensions_out() };
 
@@ -116,7 +146,22 @@ pub fn dimensions_stdout() -> Option<(usize, usize)> {
 /// terminal width. If that streams is actually a tty, this function returns its width
 /// and height as a number of characters.
 ///
-/// If *all* of the streams are not ttys or return any errors this function will return `None`.
+/// # Errors
+/// 
+/// If the stream is not a tty or return any errors this function will return `None`.
+/// 
+/// # Example
+/// 
+/// To get the dimensions of your terminal window, simply use the following:
+/// 
+/// ```no_run
+/// # use term_size;
+/// if let Some((w, h)) = term_size::dimensions_stdin() {
+///     println!("Width: {}\nHeight: {}", w, h);
+/// } else {
+///     println!("Unable to get term size :(")
+/// }
+/// ```
 pub fn dimensions_stdin() -> Option<(usize, usize)> {
     let w = unsafe { get_dimensions_in() };
 
@@ -131,7 +176,22 @@ pub fn dimensions_stdin() -> Option<(usize, usize)> {
 /// terminal width. If that streams is actually a tty, this function returns its width
 /// and height as a number of characters.
 ///
-/// If *all* of the streams are not ttys or return any errors this function will return `None`.
+/// # Errors
+/// 
+/// If the stream is not a tty or return any errors this function will return `None`.
+/// 
+/// # Example
+/// 
+/// To get the dimensions of your terminal window, simply use the following:
+/// 
+/// ```no_run
+/// # use term_size;
+/// if let Some((w, h)) = term_size::dimensions_stderr() {
+///     println!("Width: {}\nHeight: {}", w, h);
+/// } else {
+///     println!("Unable to get term size :(")
+/// }
+/// ```
 pub fn dimensions_stderr() -> Option<(usize, usize)> {
     let w = unsafe { get_dimensions_err() };
 

src/platform/windows.rs

@@ -3,7 +3,24 @@ use kernel32::{GetConsoleScreenBufferInfo, GetStdHandle};
 use winapi::{CONSOLE_SCREEN_BUFFER_INFO, COORD, SMALL_RECT, STD_OUTPUT_HANDLE};
 
 /// Query the current processes's output, returning its width and height as a
-/// number of characters. Returns `None` if the output isn't to a terminal.
+/// number of characters. 
+///
+/// # Errors
+/// 
+/// Returns `None` if the output isn't to a terminal.
+/// 
+/// # Example
+/// 
+/// To get the dimensions of your terminal window, simply use the following:
+/// 
+/// ```no_run
+/// # use term_size;
+/// if let Some((w, h)) = term_size::dimensions() {
+///     println!("Width: {}\nHeight: {}", w, h);
+/// } else {
+///     println!("Unable to get term size :(")
+/// }
+/// ```
 pub fn dimensions() -> Option<(usize, usize)> {
     let null_coord = COORD { X: 0, Y: 0 };
     let null_smallrect = SMALL_RECT {
@@ -29,10 +46,40 @@ pub fn dimensions() -> Option<(usize, usize)> {
         None
     }
 }
+
 /// Query the current processes's output, returning its width and height as a
 /// number of characters. Returns `None` if the output isn't to a terminal.
+///
+/// # Errors
+/// 
+/// Returns `None` if the output isn't to a terminal.
+/// 
+/// # Example
+/// 
+/// To get the dimensions of your terminal window, simply use the following:
+/// 
+/// ```no_run
+/// # use term_size;
+/// if let Some((w, h)) = term_size::dimensions() {
+///     println!("Width: {}\nHeight: {}", w, h);
+/// } else {
+///     println!("Unable to get term size :(")
+/// }
+/// ```
 pub fn dimensions_stdout() -> Option<(usize, usize)> { dimensions() }
+
 /// This isn't implemented for Windows
+/// 
+/// # Panics
+/// 
+/// This function `panic!`s unconditionally with the `unimplemented!`
+/// macro
 pub fn dimensions_stdin() -> Option<(usize, usize)> { unimplemented!() }
+
 /// This isn't implemented for Windows
+/// 
+/// # Panics
+/// 
+/// This function `panic!`s unconditionally with the `unimplemented!`
+/// macro
 pub fn dimensions_stderr() -> Option<(usize, usize)> { unimplemented!() }