update README.md

1 files changed, 62 insertions, 8 deletions

diff --git a/README.md b/README.md
index 4d73a7b..0e6692a 100644
--- a/README.md
+++ b/README.md
@@ -10,11 +10,20 @@ source code.
 usage
 -----
 
-The function `lily_init()` must be called exactly once before any other lily
-functions may be called.
+Tests are any function with the signature `void (void)`, and are run with the macro `lily_run_test(test)`.
+Tests are intended to be run inside of suite functions, which have the same signature as a test.
+To add suite setup or teardown operations, just do them inside the suite function.
+Suites are run with the `lily_run_suite(suite)` macro.
 
-Tests are simply functions with the signature `void ()`. Each test can contain
-any of the following assertion messages:
+Tests can contain assertions! You should not try to use these assertions outside of tests run with
+`lily_run_test()` because you'll probably just crash your program. Tests, if they fail, generate
+error messages that detail the mismatch between their expected and actual results and also indicate
+the file and line of the failed assertion. On some compilers `__FILE__` is the complete path of the 
+file (i.e. all the way from root), so lily lets you trim N characters from the front of it by 
+defining a `SOURCE_PATH_SIZE` macro whose value is N. (I usually define this from within my build tool
+so that it'll still work if other people download the software).
+
+The following assertions are available:
 
 * `lily_assert_true(bool)`
 * `lily_assert_false(bool)`
@@ -31,12 +40,57 @@ any of the following assertion messages:
 * `lily_assert_memory_equal(void *, void *, size_t size)`
 * `lily_assert_memory_not_equal(void *, void *, size_t size)`
 
-Tests are run via the macro `lily_run_test(test_func)`. A test suite is simply a `void ()` 
-function that runs some tests. Suites can be called via the macro `lily_run_suite(suite_func)`.
+lily also provides some features to make mocking functions a little nicer. First,
+there is the `lily_queue_t` object, which contains a FIFO queue for arbitrary data.
+They support the following operations:
+
+* `lily_queue_t * lily_queue_create()` - create a new queue
+* `lily_queue_destroy(lily_queue_t *)` - destroy a queue
+* `lily_enqueue(lily_queue_t*, TYPE, value)` - enqueue some value. Any type can be queued; just be careful to dequeue the same data types in the same order!
+* `lily_dequeue(lily_queue_t*, TYPE, ptr)` - pops a value from the queue into a pointer of **an appropriate type**. Be careful not to dequeue data types in the same order you queued them!
+
+This system is intended to allow you to control the behavior/return types of mock functions
+by queueing things before a call that the mock will dequeue.
+
+lily also provides the `lily_mock_t` object, which uses these queues to easily store the arguments
+of a call to a function.
+
+* `lily_mock_t * lily_mock_create()` - create a new mock object
+* `lily_mock_destroy(lily_mock_t *)` - destroy a mock object
+* `lily_mock_call(lily_mock_t*, struct lily_mock_arg_t*)` - store arguments (see below)
+* `lily_get_call(lily_mock_t*, struct lily_mock_arg_t*, int)` - store arguments (see below)
+
+Each `struct lily_mock_arg_t` contains a size and void pointer, so storing a set of arguments
+looks something like this:
+
+```
+lily_mock_t *m; // initialized somewhere
+void some_func(int a, const char *b)
+{
+	struct lily_mock_arg_t args[] = {
+		{ sizeof(int), &a },
+		{ sizeof(const char *), &b },
+	};
+	lily_mock_call(m, args);
+	/* ... */
+}
+```
+
+Retrieving calls looks much the same, except the pointers in the array are to destinations
+and not sources. (You also need to specify the zero-indexed number of the call -- that's the `int` argument).
+
+
+
+~ the future ~
+--------------
+
+Some features I'd like to add:
 
-A small script, called `prepare-tests.sh` is provided. It will automatically scan
+A `prepare-tests.sh` script that will automatically scan
 the given source root for all files matching `*.test.c` and qenerate a header file,
 main function, and Makefile to run all of the functions matching `void ()` in those
 test files. (If you want a utility function or something, just make it `static`).
-This script relies on POSIX utilities -- sorry, Windows users. :l
 
+It might be nice to switch to an stb-style header-only library, where the contents of
+`lily-test.c` are put inside of a macro gate, and the user just has to `#define LILY_IMPLEMENTATION`
+in some file that includes `lily-test.h`.