improve readme

README.rst

@@ -5,13 +5,56 @@ stub
    :height: 200px
    :width: 200px
 
+.. image:: http://buildbot.steinwurf.dk/svgstatus?project=stub
+    :target: http://buildbot.steinwurf.dk/stats?projects=stub
+
 Overview
 ========
-stub is a simple C++ library that is meant to provide simple helper
+stub is a simple C++ library which is meant to provide simple helper
 functions to ease sometimes tedious testing tasks.
 
-.. image:: http://buildbot.steinwurf.dk/svgstatus?project=stub
-    :target: http://buildbot.steinwurf.dk/stats?projects=stub
+stub is especially helpful when testing template functions which
+takes hard-to-construct objects as parameters.
+With stub the task of making such tests short and self-contained, becomes much
+simpler. See this example of how `function_to_test` is tested:
+
+::
+
+    #include <stub/function.hpp>
+    #include <cassert>
+
+    template<class T>
+    void function_to_test(T& t)
+    {
+        t.some_function(4);
+
+        if (t.some_check())
+        {
+            t.do_something_else(false);
+        }
+    }
+
+    struct dummy
+    {
+        stub::function<void(int)> some_function;
+        stub::function<bool()> some_check;
+        stub::function<void(bool)> do_something_else;
+    };
+
+    void main()
+    {
+        // Construct object
+        dummy obj;
+        obj.some_check.set_return(true);
+
+        // Run function
+        function_to_test(obj);
+
+        // Check calls
+        assert(obj.some_function.expect_calls().with(4));
+        assert(obj.some_check.calls() == 1);
+        assert(obj.do_something_else.expect_calls().with(false));
+    }
 
 .. contents:: Table of Contents:
    :local:

test/src/test_readme.cpp

@@ -7,7 +7,42 @@
 
 #include <gtest/gtest.h>
 
+namespace
+{
+    template<class T>
+    void function_to_test(T& t)
+    {
+        t.some_function(4);
+
+        if (t.some_check())
+        {
+            t.do_something_else(false);
+        }
+    }
+
+    struct dummy
+    {
+        stub::function<void(int)> some_function;
+        stub::function<bool()> some_check;
+        stub::function<void(bool)> do_something_else;
+    };
+}
 /// Tests that all the examples given in the readme works as advertised
+TEST(test_readme, usage)
+{
+        // Construct object
+        dummy obj;
+        obj.some_check.set_return(true);
+
+        // Run function
+        function_to_test(obj);
+
+        // Check calls
+        assert(obj.some_function.expect_calls().with(4));
+        assert(obj.some_check.calls() == 1);
+        assert(obj.do_something_else.expect_calls().with(false));
+}
+
 TEST(test_readme, check_a_set_of_function_calls)
 {
     stub::function<void(uint32_t)> some_function;