From 321a3664efc9b159933483c08b08a1ae6f50fdb0 Mon Sep 17 00:00:00 2001
From: yamadapc <tacla.yamada@gmail.com>
Date: Wed, 9 Jul 2014 23:24:24 -0300
Subject: [PATCH] Start adding proper documentation.

I still have to add travis-ci testing and publish this package to the
dub directory.
---
 README.md         | 68 ++++++++++++++++++++++++++++++++++++++++++++---
 source/colorize.d | 26 ++++++++++++++++++
 2 files changed, 91 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 21831b6..3362bb4 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,71 @@
 d-colorize
 ====================
 
-__THIS MODULE HASN'T BEEN PROPERLY TESTED OR PUBLISHED YET__
-__(but it's trivial, so it shouldn't take too much)__
-__TODO__
+__THIS MODULE HASN'T BEEN PUBLISHED YET__
+
+# Usage
+```d
+import std.stdio;
+import colorize;
+
+void main()
+{
+  writeln("This is blue".colorize(fg.blue));
+}
+```
+
+# `colorize(string str, fg c, bg b=bg.init, mode m=mode.init)`
+
+Wraps a string around color escape sequences.
+
+## Params
+* str = The string to wrap with colors and modes
+* c   = The foreground color (see the fg enum type)
+* b   = The background color (see the bg enum type)
+* m   = The text mode        (see the mode enum type)
+
+## Example
+
+```d
+colorize("This is red over green blinking", fg.blue, bg.green, mode.blink)
+```
+
+# Available colors and modes
+## `fg` enum type (Foreground colors)
+Foreground text colors are available through the `fg` enum. Currently available
+colors are:
+- `fg.init` (39)
+- `fg.black` (30)
+- `fg.red` (31)
+- `fg.green` (32)
+- `fg.yellow` (33)
+- `fg.blue` (34)
+- `fg.magenta` (35)
+- `fg.cyan` (36)
+- `fg.white` (37)
+- `fg.light\_black` (90)
+- `fg.light\_red` (91)
+- `fg.light\_green` (92)
+- `fg.light\_yellow` (93)
+- `fg.light\_blue` (94)
+- `fg.light\_magenta` (95)
+- `fg.light\_cyan` (96)
+- `fg.light\_white` (97)
+
+## `bg` enum type (Background colors)
+Background colors are available with the same names through the `bg` enum. This
+is because background colors come with an offset of 10 to their foreground
+counterparts and we wanted to avoid calculating the offset at runtime.
+
+## `mode` enum type (Text modes)
+Text modes are available through the `mode` enum. Currently available text modes
+are:
+- `mode.init` (0)
+- `mode.bold` (1)
+- `mode.underline` (4)
+- `mode.blink` (5)
+- `mode.swap` (7)
+- `mode.hide` (8)
 
 ## License
 Copyright (c) 2014 Pedro Tacla Yamada. Licensed under the MIT license.
diff --git a/source/colorize.d b/source/colorize.d
index ae984d3..c823204 100644
--- a/source/colorize.d
+++ b/source/colorize.d
@@ -1,5 +1,13 @@
+/**
+ * Authors: Pedro Tacla Yamada
+ * Date: June 9, 2014
+ * License: Licensed under the MIT license. See LICENSE for more information
+ * Version: 0.0.1
+ */
+
 import std.string : format;
 
+// Foreground colors
 static enum fg : int
 {
   init = 39,
@@ -23,6 +31,7 @@ static enum fg : int
   light_white   = 97
 }
 
+// Background colors
 static enum bg : int
 {
   init = 49,
@@ -46,6 +55,7 @@ static enum bg : int
   light_white   = 107
 }
 
+// Text modes
 static enum mode : int
 {
   init      = 0,
@@ -56,6 +66,22 @@ static enum mode : int
   hide      = 8
 }
 
+/**
+ * Wraps a string around color escape sequences.
+ *
+ * Params:
+ *   str = The string to wrap with colors and modes
+ *   c   = The foreground color (see the fg enum type)
+ *   b   = The background color (see the bg enum type)
+ *   m   = The text mode        (see the mode enum type)
+ * Example:
+ * ---
+ * writeln("This is blue".colorize(fg.blue));
+ * writeln(
+ *   colorize("This is red over green blinking", fg.blue, bg.green, mode.blink)
+ * );
+ * ---
+ */
 
 string colorize(string str, fg c, bg b=bg.init, mode m=mode.init)
   pure