From 7d7bf5c197d5e29f86db3c1412822411dc52ebd1 Mon Sep 17 00:00:00 2001
From: Jon Michael Aanes <jonjmaa@gmail.com>
Date: Thu, 17 Apr 2025 16:37:54 +0200
Subject: [PATCH] improved documentation v2

---
 assert-gooder.lua | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/assert-gooder.lua b/assert-gooder.lua
index df88739..46a8064 100644
--- a/assert-gooder.lua
+++ b/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'