update documentation for new version

8 files changed, 103 insertions, 68 deletions

diff --git a/doc/a_simple_example.c b/doc/a_simple_example.c
deleted file mode 100644
index 6784713..0000000
--- a/doc/a_simple_example.c
+++ /dev/null
@@ -1,68 +0,0 @@
-/* keep this include at the very top of the file */
-#include "../src/simple-test.h"
-
-/* any global variables, functions, other inclusions, etc.
- * should be declared here */
-#include "header_with_stuff_to_be_tested.h"
-
-int add_here(int a, int b)
-{
-	/* ASSERT / ECHO statements within functions
-	 * like this are perfectly valid. this is
-	 * useful for writing initialisation functions
-	 * called at the beginning of multiple TESTs */
-	ECHO("this is the local add");
-
-	/* ensure a and b are non-0 using generic ASSERT */
-	ASSERT(a);
-	ASSERT(b);
-
-	return a + b;
-}
-
-/* must come before all TESTs */
-BEGIN_TEST
-
-/* the string is a description of the test being run */
-TEST("check add()'s return value")
-{
-	/* mixing different precisions is allowed */
-	long var1 = 2;
-	int8_t var2 = 2;
-
-	/* add is a function included from our hypothetical
-	 * header_with_stuff_to_be_tested.h */
-	ASSERT_INT_EQ(var1+var2, add(var1, var2));
-
-	/* generic versions of ASSERTions are also valid,
-	 * but only for number types (int / uint / float ) */
-	ASSERT_EQ(var1+var2, add_here(var1, var2));
-}
-
-TEST("compare two arrays of strings")
-{
-	int i;
-	char array1[][10] = {
-		"str1",
-		"str2",
-		"str3",
-	};
-	char array2[][10] = {
-		"str1",
-		"str2",
-		/* matching will fail here */
-		"different",
-	};
-
-	for(i = 0; i < sizeof(array1) / sizeof(char[10]); i++) {
-		/* ECHO can be used to print (with pretty
-		 * formatting) the current state within the
-		 * test */
-		ECHO("checking strs at i == %i", i);
-
-		ASSERT_STR_EQ(array1[i], array2[i]);
-	}
-}
-
-/* must come after all TESTs */
-END_TEST
diff --git a/doc/example.c b/doc/example.c
new file mode 100644
index 0000000..26d8f66
--- /dev/null
+++ b/doc/example.c
@@ -0,0 +1,103 @@
+#include "../simple-test.h"
+
+/* global variables, functions, and includes must come before BEGIN_TEST */
+char *global_s;
+
+/* a teardown function is called by TESTs which include USE_TEARDOWN. the call
+ * occurs either after an ASSERT fails or after the TEST is finished.
+ *
+ * defining one is optional, but, if used, REGISTER_TEARDOWN must appear
+ * between BEGIN_TEST and the first TEST
+ * 
+ * here i'm using it to free memory that's alloced inside tests below */
+void teardown(void)
+{
+	free(global_s);
+}
+
+/* must appear before an (optional) REGISTER_TEARDOWN and all TESTs */
+BEGIN_TEST
+
+/* if used, must appear before first TEST and after BEGIN_TEST */
+REGISTER_TEARDOWN(teardown);
+
+/* run a test. provided description must be a string literal */
+TEST("basic assertion")
+{
+	/* ASSERT fails if passed some sort of non-true value (0, false, NULL) */
+	ASSERT(1);
+}
+
+TEST("basic not assertion")
+{
+	bool b = false;
+
+	ASSERT_NOT(b);
+}
+
+TEST("boolean comparison")
+{
+	bool a = false, b = true;
+
+	/* fail if parameters are not equal */
+	ASSERT_EQ(a, b);
+}
+
+TEST("type mismatch")
+{
+	char a = 'a';
+	int i = 97;
+	char *b = NULL;
+
+	/* for convenience's sake, when presented with unmatched types, assertions
+	 * try to resolve them in a way that's most likely to match the
+	 * programmer's intentions. here 'i' is interpreted as a char */
+	ASSERT_EQ(a, i);
+
+	/* if there isn't a straightforward comparison to make, though (as is the
+	 * case here, with a 'char' and 'char *'), a type mismatch error occurs */
+	ASSERT_EQ(a, b);
+}
+
+TEST("ECHO example")
+{
+	int i;
+
+	/* ECHO can be used to neatly report information during a run */
+	if (true)
+		ECHO("loop until i not less than 1");
+
+	for (i = 0; i < 2; i++) {
+		/* it takes printf format strings and variable args as well */
+		ECHO("i == %d", i);
+		ASSERT_LT(i, 1);
+	}
+}
+
+TEST("string comparison")
+{
+	char *s = "test";
+	global_s = strdup("test");
+
+	/* USE_TEARDOWN; tells this test to call the previously defined teardown
+	 * function on exiting (successfully or otherwise) */
+	USE_TEARDOWN;
+
+	/* strings are compared by content, so this assertion succeeds */
+	ASSERT_EQ(s, global_s);
+}
+
+TEST("pointer comparison")
+{
+	char *s = "test";
+	global_s = strdup("test");
+	USE_TEARDOWN;
+
+	/* you can cast parameters in order to use a different type of comparison.
+	 * here i'm casting the 'char *' to 'void *' so assertion performs a
+	 * pointer comparison, which fails */
+	ASSERT_EQ((void*)s, (void*)global_s);
+}
+
+/* must come after all TESTs */
+END_TEST
diff --git a/doc/run-01.png b/doc/run-01.png
deleted file mode 100644
index b7c6838..0000000
--- a/doc/run-01.png
+++ /dev/null
diff --git a/doc/run-02.png b/doc/run-02.png
deleted file mode 100644
index aedd395..0000000
--- a/doc/run-02.png
+++ /dev/null
diff --git a/doc/run-03.png b/doc/run-03.png
deleted file mode 100644
index f6843dc..0000000
--- a/doc/run-03.png
+++ /dev/null
diff --git a/doc/run_01.png b/doc/run_01.png
new file mode 100644
index 0000000..df74574
--- /dev/null
+++ b/doc/run_01.png
diff --git a/doc/run_02.png b/doc/run_02.png
new file mode 100644
index 0000000..b84d5e5
--- /dev/null
+++ b/doc/run_02.png
diff --git a/doc/run_03.png b/doc/run_03.png
new file mode 100644
index 0000000..05fd99c
--- /dev/null
+++ b/doc/run_03.png