CL-MOCK - Mocking (generic) functions.
-Copyright (C) 2013 Olof-Joachim Frahm
+Copyright (C) 2013-14 Olof-Joachim Frahm
Release under a Simplified BSD license.
Should be portable thanks to [`CLOSER-MOP`][1].
+
+# INTRODUCTION
+
+This small library provides a way to replace the actual implementation
+of either regular or generic functions with mocks. How to integrate
+this facility with a testing library is up to the user; the tests for
+the library are written in [`FIVEAM`][2] though, so most examples will
+take that into account.
+
Since it is pretty easy to just roll something like this on your own,
-the main purpose is to develop a nice syntax (lispy, declarative) to
-keep tests readable and maintainable.
+the main purpose is to develop a nice (lispy, declarative) syntax to
+keep your tests readable and maintainable.
Some parts may be used independently of the testing facilities,
e.g. dynamic `FLET` and method bindings with `PROGM` may be of general
interest.
+# MOCKING CONTEXT
+
+In addition to having macros and functions to install bindings into the
+mocking context, the actual context object may be retrieved and passed
+around as well. This might be useful for further analysis or other
+helpers.
+
+
# GENERIC FUNCTIONS
Since behaviour isn't bound to classes, but to generic functions,
-creating new classes on the fly isn't particularly interesting.
+creating new classes on the fly isn't particularly interesting. If
+necessary, additional shortcuts will be added, but until then I don't
+see the need for this. On the contrary, providing a way to temporarily
+supersede generic function bindings sounds like a more viable approach,
+especially with regards to (custom) method combinations.
-We provide the form `PROGM` to bind a number of methods during the
-execution of its contained body:
+Thus, the form `PROGM` is provided to bind a number of methods during
+the execution of its body:
> (progm
> '((baz NIL (list)))
> => 42
> => (1 2 3)
+This is implemented via [`CLOSER-MOP`][1], so compatiblity with that
+library is required.
+
# UTILITIES
> => 23
> (OR) => 42, if FOO was inlined
-The caveat is that this might not work on certain optimization settings,
-including inlining.
+The caveat is that this might not work on certain optimisation settings,
+including inlining. That trade-off seems acceptable; it would be nice
+if a warning could be issued depending on the current optimisation
+settings, however that is particularly implementation dependent, so lack
+of a warning won't indicate a working environment.
-The underlying function `PROGF` may be used as well similarly to standard
-`PROG`:
+The underlying function `PROGF` may be used as well similarly to the
+standard `PROG`:
> (progf '(foo) (list (lambda () 23))
> (bar))