improved documentation v2

assert-gooder.lua

@@ -7,6 +7,38 @@
 -- assert condition, inspects the state of the program and emits an improved
 -- error message.
 --
+--
+-- ## Example
+--
+-- ```lua
+-- function f (a)
+--     assert(type(a) == 'string')
+-- end
+--
+-- f(42)
+-- ```
+--
+-- Without `assert-gooder`, the above code would fail with the error message
+-- `assertion failed!`. With `assert-gooder`, it will fail with this error message:
+-- `assertion failed! bad argument #1 'a' to 'f' (string expected, but got number: 42)`,
+--
+-- ## Motivation
+--
+-- Assertions are useful to ensure internal consistency, when you're writing code
+-- in a hurry, but in Lua (and most other languages), these assert constructs never
+-- produce useful error messages, but rather unhelpful `assert failed!` errors and
+-- a stack trace.
+--
+-- By making it a runtime library, instead of a "compile-time" rewrite, we gain
+-- flexibility. It's much easier to import a library, than restructuring then
+-- compile pipeline. It also means that we have access to runtime values, allowing
+-- even more helpful messages.
+--
+-- ## Setup
+--
+-- Download, and use `assert = require "assert-gooder"` to overwrite Lua's default
+-- assert with `assert-gooder`.
+--
 -- @author Jon Michael Aanes (jonjmaa@gmail.com)
 
 local _VERSION = '0.5.2'