From fd1cd7820d913eba1190b300c470b0ed1f91692d Mon Sep 17 00:00:00 2001
From: Phil Nash <github@philnash.me>
Date: Mon, 10 Jun 2013 08:18:26 +0100
Subject: [PATCH] Completed assertions docs

---
 docs/assertions.md | 56 +++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 55 insertions(+), 1 deletion(-)

diff --git a/docs/assertions.md b/docs/assertions.md
index 1db0a610..114c841b 100644
--- a/docs/assertions.md
+++ b/docs/assertions.md
@@ -1,4 +1,58 @@
-placeholder for assertion macros
+# Assertion Macros
+
+Most test frameworks have a large collection of assertion macros to capture all possible conditional forms (_EQUALS, _NOTEQUALS, _GREATER_THAN etc).
+
+Catch is different. Because it decomposes natural C-style conditional expressions most of these forms are reduced to one or two that you will use all the time. That said there are a rich set of auxilliary macros as well. We'll describe all of these here.
+
+Most of these macros come in two forms:
+
+## Natural Expressions
+
+The REQUIRE family of macros tests an expression and aborts the test case if it fails.
+The CHECK family are equivalent but execution continues in the same test case even if the assertion fails. This is useful if you have a series of essentially orthoginal assertions and it is useful to see all the results rather than stopping at the first failure.
+
+**REQUIRE(** _expression_ **)** and  
+**CHECK(** _expression_ **)**  
+Evaluates the expression and records the result. If an exception is thrown it is caught, reported, and counted as a failure. These are the macros you will use most of  the time
+
+Examples:
+
+```c++
+CHECK( str == "string value" );
+CHECK( thisReturnsTrue() );
+REQUIRE( i == 42 );
+```
+**REQUIRE_FALSE(** _expression_ **)** and  
+**CHECK_FALSE(** _expression_ **)**  
+Evaluates the expression and records the _logical NOT_ of the result. If an exception is thrown it is caught, reported, and counted as a failure.
+(these forms exist as a workaround for the fact that ! prefixed expressions cannot be decomposed).
+
+Example:
+```c++
+REQUIRE_FALSE( thisReturnsFalse() );
+```
+
+## Exceptions
+
+**REQUIRE_THROWS(** _expression_ **)** and  
+**CHECK_THROWS(** _expression_ **)**  
+Expects that an exception (of any type) is be thrown during evaluation of the expression.
+
+**REQUIRE_THROWS_AS(** _expression_ and _exception type_ **)** and  
+**CHECK_THROWS_AS(** _expression_, _exception type_ **)**  
+Expects that an exception of the _specified type_ is thrown during evaluation of the expression.
+
+**REQUIRE_NOTHROW(** _expression_ **)** and  
+**CHECK_NOTHROW(** _expression_ **)**  
+Expects that no exception is thrown during evaluation of the expression.
+
+## Matcher expressions
+
+To support Matchers a slightly different form is used. Matchers will be more fully documented elsewhere. *Note that Matchers are still at early stage development and are subject to change.*
+
+**REQUIRE_THAT(** _lhs_, __matcher call__ **)** and  
+**CHECK_THAT(** _lhs_, __matcher call__ **)**  
+
 
 ---