From: Olof-Joachim Frahm <olof@macrolet.net>
Date: Wed, 17 Dec 2014 20:42:43 +0000 (+0000)
Subject: Add introduction paragraph.
X-Git-Tag: 1.0.0~4
X-Git-Url: http://repo.macrolet.net/gitweb/?p=cl-mock.git;a=commitdiff_plain;h=ead1bffcbb443b339cd65488994cde6d271781c3

Add introduction paragraph.
---

diff --git a/README.md b/README.md
index ad9bcb6..d453b5a 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 CL-MOCK - Mocking (generic) functions.
 
-Copyright (C) 2013 Olof-Joachim Frahm
+Copyright (C) 2013-14 Olof-Joachim Frahm
 
 Release under a Simplified BSD license.
 
@@ -10,22 +10,43 @@ Working, but unfinished.
 
 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)))
@@ -44,6 +65,9 @@ For example:
     > => 42
     > => (1 2 3)
 
+This is implemented via [`CLOSER-MOP`][1], so compatiblity with that
+library is required.
+
 
 # UTILITIES
 
@@ -58,11 +82,14 @@ For example:
     > => 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))