started writing documentation

README.md

@@ -1,16 +1,103 @@
 # 9unit
 Copyright (C) 2023  Jonathan Lamothe <jonathan@jlamothe.net>
 
-This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
 
-This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
+This program is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
 
-You should have received a copy of the GNU Lesser General Public License along with this program.  If not, see <http://www.gnu.org/licenses/>.
+You should have received a copy of the GNU Lesser General Public
-
+License along with this program.  If not, see
-## WARNING
+<http://www.gnu.org/licenses/>.
-
-This library is experimental and should be considered subject to change at any time.
 
 ## Summary
 
-A simple C testing framework for Plan9
+A simple unit testing framework for C programs in Plan9
+
+This provides the library file `9unit.a` and the header `9unit.h`.
+The header file is relatively well commented and can provide a fairly
+comprehensive breakdown of the API.  This document will however
+provide a basic overview below.
+
+This library is used to test the library itself, consequently, the
+`test` directory contains a relitively decent real-world example of
+how it can be used.
+
+## `TestState`
+
+The entire testing framework is centred around the `TestState` data
+structure.  As its name would imply, it contains the current state of
+the tests in progress, however it should almost never be necessary to
+interact with it directly.  With the exception of `run_tests()`
+(described below), all functions provided by the library will take
+take a pointer to a `TestState` value as their first parameter.
+
+## `run_tests()`
+
+This will typically be the first function you call in your tests.  It
+sets up the testing framework, creates an initial `TestState` value,
+runs the tests provided to it and displays a log and summary at the
+end.  If any of the provided tests failed, it will cause the test
+program to exit with status of `"test(s) failed"`.  Its prototype
+follows:
+
+```C
+void run_test(void (*tests)(TestState *))
+```
+
+The `tests` parameter is a pointer to a function which then is
+responsible for running the actual tests.  A pointer to the newly
+created `TestState` value will be passed to this function.
+
+## Simple Tests
+
+The simplest form of test can be represented as a function resembling
+the follwoing:
+
+```C
+TestResult my_test(TestState *s)
+{
+	// ...
+}
+```
+
+This function should return a `TestResult` value representing (perhaps
+unsurprisingly) the result of the test.  The options are as follows:
+
+- `test_success`: the test was completed successfully
+- `test_failure`: the test failed
+- `test_pending`: the test is pending and should be ignored for now
+
+Tests of this type can be run by passing them to the `run_test()`
+function, which has the following prototype:
+
+```C
+void run_test(
+	TestState *s,
+	TestResult (*test)(TestState *)
+)
+```
+
+This function will run the provided test and update the provided
+`TestState` to reflect the result of the test.
+
+## Passing Values to Tests
+
+Since C supports neither lambdas nor closures, this leaves one with
+little choice but to come up with a unique name for each test
+function.  This, while possible, would definitely be rather
+inconvenient.  To combat this, it is helpful to be able to pass data
+into a generic test so that it can be reused multiple times.
+
+### The `ptr` Value
+
+The `TestState` struct has a value called `ptr` which is a void
+pointer that can be set prior to calling `run_test()`.  This value can
+then be read by the test function, giving you the ability to
+essentially pass in *any* type of data you may need.  While not ideal,
+it's *a* solution.