(hopefully) cute readme

README.md

@@ -0,0 +1,89 @@
+# Termprogress - Terminal progress bars
+Simple and customiseable terminal progress bars for Rust.
+
+## Features
+
+ - Customiseable, has a traits system to allow for passing any type of progress bar around
+ - Prevents long titles from overflowing the terminal by using the [terminal_size][terminal-size] crate
+ - Interfaces for easily manipulating bar
+ 
+[terminal-size]: https://crates.io/crates/terminal_size
+
+## How it looks
+
+The bar at 50, 75, and 100%:
+
+``` shell
+[=========================                         ]: 50.00% some title
+[=====================================             ]: 75.00% some other title
+[==================================================]: 100.00% some other title
+```
+
+The spinner in 4 stages:
+
+``` shell
+Some title /
+Some title -
+Some title \
+Some title |
+```
+
+## Getting started.
+To quickly use the default bar and spinner, you can include the `prelude`:
+
+``` rust
+use termprogress::prelude::*;
+
+let mut progress = Bar::default(); // Create a new progress bar
+
+progress.set_title("Work is being done...");
+/// *does work*
+progress.set_progress(0.25);
+progress.set_progress(0.5);
+progress.println("Something happened");
+progress.set_progress(0.75);
+progress.println("Almost done...");
+progress.set_progress(1.0);
+
+/// completes
+progress.complete();
+```
+
+Spinner:
+
+``` rust
+use termprogress::prelude::*;
+
+let mut spinner = Spin::default(); //Create a new spinner
+/// *does work*
+spinner.bump();
+spinner.bump();
+progress.println("Something happened");
+spinner.bump();
+spinner.bump();
+
+/// completes
+progress.complete_with("Done!");
+```
+
+## Traits
+The library comes with traits for progress bars: `[ProgressBar][progress-bar]`, and `[Spinner][spinner]`.
+
+The default implementations for these are `Bar` and `Spin`, but you can provide your own implementations too for more customisability
+
+``` rust
+pub fn does_work<P: ProgressBar>(bar: &mut P) 
+{
+	//does work...
+	bar.set_progress(0.5);
+	//more work...
+	bar.set_progress(1.0);
+}
+
+does_work(&mut Bar::default());
+does_work(&mut MyBar::new());
+```
+
+## License
+GPL'd with love <3
+

src/inter.rs

@@ -22,14 +22,14 @@ pub trait Display
     fn update_dimensions(&mut self, to: usize);
 }
 
-/// A bar with progress
+/// A trait for any bar with progress. You can implemnent your own styles through this trait.
 pub trait ProgressBar: Display
 {   
     fn set_progress(&mut self, value: f64);
     fn get_progress(&self) -> f64;
 }
 
-/// A bar without progress
+/// A trait for any bar without progress. You can implemnent your own styles through this trait.
 pub trait Spinner: Display
 {   
     fn bump(&mut self);

src/lib.rs

@@ -12,11 +12,16 @@ macro_rules! flush {
 mod util;
 mod inter;
 pub use inter::*;
+
 pub mod progress;
 pub mod wheel;
 pub mod spinner;
 
-#[cfg(test)]
-mod tests {
-    
+/// The prelude exposes the traits for spinners and progress bars, and the `spinner::Spin` and `progress::Bar` types for easy access and use.
+pub mod prelude {
+    pub use super::inter::*;
+    pub use super::{
+	spinner::Spin,
+	progress::Bar,
+    };
 }

src/progress.rs

@@ -1,8 +1,26 @@
+///! Progress bar that has a size and also a max size.
+
 use super::*;
 use std::{
     fmt::Write,
 };
 
+/// A progress bar with a size and optionally title. It implements the `ProgressBar` trait, and is the default progress bar.
+///
+/// The bar has a max size, that is usually derived from the size of your terminal (if it can be detected) or can be set yourself, to stop the title line going over the side.
+/// It also has a configurable width, which is defaulted to 50.
+///
+/// # Usage
+///
+/// To create a new `progress::Bar` with a max size tuned to your terminal (or `Width+20`, if it cannot be detected), and of the default size, `Bar` implements the `Default` trait:
+/// ```rust
+/// let mut bar = Bar::default(); //Creates a bar of width 50 by default.
+/// ```
+///
+/// You can configure sizes and initial title with `new()`, `with_title()`, and `with_max()` functions.
+/// # How it looks
+/// It renders in the terminal like:
+/// `[=========================                         ]: 50% this is a title that may get cut if it reaches max le...`
 #[derive(Debug)]
 pub struct Bar
 {
@@ -13,34 +31,13 @@ pub struct Bar
     title: String,
 }
 
-/*
-#[cfg(test)]
-mod tests
+impl Default for Bar
 {
-    #[test]
-    fn display()
+    fn default() -> Self
     {
-	
-	let mut bar = Bar::new(50);
-	bar.set_title("hello world");
-	bar.progress = 0.455456749849;
-	bar.update();
-	bar.refresh();
-	bar.progress = 0.8;
-	bar.update();
-	bar.refresh();
-	bar.progress = 0.88;
-	bar.update();
-	bar.refresh();
-	bar.set_title("almost AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA");
-	bar.progress = 0.99554;
-	bar.update();
-	bar.refresh();
-
-	println!("\nuhh");
-	panic!("h");
-    }
-}*/
+	Self::new(50)
+    }
+}
 
 impl Bar
 {

src/spinner.rs

@@ -1,5 +1,21 @@
+///! A simple character spinner for bars with no known size
+
 use super::*;
 
+/// A single character spinner with optional title that can be told to spin whenever it wants. It implements `Spinner` trait, and is the default spinner.
+///
+/// The spinner takes up a line, and renders it's spinner on the end of its title. Calling the `Spinner::bump()` function will cause the character sequence to advance.
+///
+/// # Usage
+/// To use the spinner you can provide it a `Wheel` (see [[wheel]] module), or it implements the `Default` trait, creating a traditional looking spinner (`|/-\`)
+///
+/// ```rust
+/// let mut spin = Spin::default(); //Default new spinner without a title.
+/// ```
+///
+/// # How it looks
+/// It renders in the terminal like:
+/// `This is a spinner /`
 pub struct Spin
 {
     title: String,
@@ -9,7 +25,9 @@ pub struct Spin
 
 impl Spin
 {
-    /// Create a new spinner with title
+    /// Create a new spinner with title and wheel.
+    ///
+    /// To give it the default wheel, you can pass `whl` `Default::default()` to use the default one.
     pub fn with_title(title: &str, whl: wheel::Wheel) -> Self
     {
 	let mut chars = whl.into_iter();
@@ -20,7 +38,12 @@ impl Spin
 	    chars,
 	}
     }
-    /// Create a new blank spinner
+    /// Create a new blank spinner with a wheel
+    ///
+    /// # Example
+    /// ```rust
+    ///  Spin::new(Default::default()); // Create a spinner with the default wheel ('|/-\')
+    /// ```
     pub fn new(whl: wheel::Wheel) -> Self
     {
 	let mut chars = whl.into_iter();
@@ -32,12 +55,12 @@ impl Spin
 	}
     }
 
-    /// Consume the spinner and complete it
+    /// Consume the spinner and complete it. Removes the spin character.
     pub fn complete(self) {
 	println!("{} ", (8u8 as char));
     }
     
-    /// Consume the spinner and complete it with a message
+    /// Consume the spinner and complete it with a message. Removes the spin character and then prints the message.
     pub fn complete_with(self, msg: &str)
     {
 	println!("{}{}", (8u8 as char), msg);
@@ -56,27 +79,6 @@ impl Default for Spin
     }
 }
 
-/*
-#[cfg(test)]
-mod tests
-{
-    #[test]
-    fn test()
-    {
-	const MAX: usize = 1000000;
-	let mut spin = Spin::with_title("Working maybe...", Default::default());
-	for i in 0..=MAX
-	{
-	    spin.bump();
-	    if i == MAX / 2 {
-		spin.set_title("Working more...");
-	    }
-	}
-	spin.complete_with("OK");
-	println!("Oke");
-    }
-}*/
-
 impl Display for Spin
 {
     fn refresh(&self)

src/wheel.rs

@@ -1,4 +1,8 @@
+///! Contains infinite `char` iterators and the type wrapping them, `Wheel`.
 
+/// An infinite repeating series of `char`. Used for `spinner::Spin`.
+///
+/// It implements the `IntoIterator` trait, yielding an infinite iterator of a repeating series of `char`s.
 #[derive(Clone,Debug)]
 pub enum Wheel
 {
@@ -8,12 +12,15 @@ pub enum Wheel
 
 impl Wheel
 {
+    /// Create a new spinner out of an interator of `char`.
     pub fn new<T>(iter: T) -> Self
     where T: IntoIterator<Item=char>
     {
 	let col: Vec<char> = iter.into_iter().collect();
 	Self::Dynamic(col.into_boxed_slice())
     }
+
+    /// Get a reference to all the possible chars of this wheel.
     pub fn chars(&self) -> &[char]
     {
 	match &self
@@ -34,6 +41,8 @@ impl Default for Wheel
 
 const DEFAULT_WHEEL: Wheel = Wheel::Static(&['/', '-', '\\', '|']);
 
+/// An infinite iterator of a repeating series of `char`s, used for `spinner::Spin`
+#[derive(Debug, Clone)]
 pub struct WheelIntoIter
 {
     source: Wheel,