From c12676e3deffaa6f09b7413b268159a8c538b2ba Mon Sep 17 00:00:00 2001
From: bumbread <thebumboni@gmail.com>
Date: Fri, 29 Jul 2022 05:46:13 +1100
Subject: [PATCH] assert.h documentation

---
 doc/assert.md      | 84 ++++++++++++++++++++++++++++++++++++++++++++++
 doc/readme.md      | 44 ++++++++++++++++++++++++
 test/test_assert.c | 20 +++++------
 3 files changed, 136 insertions(+), 12 deletions(-)
 create mode 100644 doc/assert.md
 create mode 100644 doc/readme.md

diff --git a/doc/assert.md b/doc/assert.md
new file mode 100644
index 0000000..67ed8be
--- /dev/null
+++ b/doc/assert.md
@@ -0,0 +1,84 @@
+
+# assert.h - debug assertions
+
+Macro definitions:
+
+- [`assert(expr)`](#assert)
+- [`static_assert`](#static-assert)
+
+## [assert](#assert)
+
+Assert a given condition is true, otherwise abort execution of a program.
+
+<details><summary>Description</summary>
+
+The macro checks whether `expr` is true, and if not, prints the
+information about where the error occurs and then aborts execution in a way
+equivalent to calling abort() function (See SIGABRT).
+
+You can disable the assertion checks by defining NDEBUG macro.
+
+</details>
+
+<details><summary>Declaration</summary>
+
+```c
+#if defined(NDEBUG)
+    #define assert(expr) ((void)0)
+#else
+    #define assert(expr) /* see description */
+#endif
+```
+</details>
+
+<details>
+<summary>Example</summary>
+
+```c
+// Uncomment to disable assert
+//#define NDEBUG
+#include <assert.h>
+
+int factorial(int n) {
+    assert(n >= 0);
+    if(n == 0) return 1;
+    return n*factorial(n-1);
+}
+
+int main() {
+    printf("Factorial of %d is %d\n", 10, factorial(10));
+    printf("Factorial of %d is %d\n", -1, factorial(-1));
+    return 0;
+}
+```
+
+The first function would print 3628800, the second would trigger an assert.
+Output:
+
+```
+Factorial of 10 is 3628800
+Assertion failed: n >= 0
+  Function: factorial
+  File: test\test_assert.c
+  Line: 4
+Trace:
+  4: factorial
+  3: main
+  2: mainCRTStartup
+  1: BaseThreadInitThunk
+  0: RtlUserThreadStart
+```
+</details>
+
+## [static_assert](#static-assert)
+
+Keyword macro that expands to C11 keyword `_Static_assert`.
+
+<details>
+<summary>Definition</summary>
+
+```c
+#define static_assert _Static_assert
+```
+</details>
+
diff --git a/doc/readme.md b/doc/readme.md
new file mode 100644
index 0000000..269000d
--- /dev/null
+++ b/doc/readme.md
@@ -0,0 +1,44 @@
+
+# Ciabatta
+
+Ciabatta is a C standard library implementation. The goal is to provide a
+cross-platform implementation that provides it's own documentation, clarifying
+implementation-defined details, as well as provides additional functionality,
+like sockets, or unicode processing, the kind of functionality that is used
+in different kinds of programs.
+
+## Headers
+
+The implementation doesn't provide all headers. The headers that aren't
+provided are supposed to be provided by compiler. The list of such headers:
+
+- float.h
+- iso646.h
+- limits.h
+- stdalign.h
+- stdarg.h
+- stdbool.h
+- stddef.h
+- stdint.h
+- stdnoreturn.h
+
+The headers that are provided have documentation included:
+
+- [assert.h](assert.md)
+- [complex.h](complex.md)
+- [ctype.h](ctype.md)
+- [errno.h](errno.md)
+- [fenv.h](fenv.md)
+- [inttypes.h](inttypes.md)
+- [locale.h](locale.md)
+- [math.h](math.md)
+- [signal.h](signal.md)
+- [stdio.h](stdio.md)
+- [stdlib.h](stdlib.md)
+- [string.h](string.md)
+- [tgmath.h](tgmath.md)
+- [threads.h](threads.md)
+- [time.h](time.md)
+- [uchar.h](uchar.md)
+- [wchar.h](wchar.md)
+- [wctype.h](wctype.md)
diff --git a/test/test_assert.c b/test/test_assert.c
index 259a2ce..879d912 100644
--- a/test/test_assert.c
+++ b/test/test_assert.c
@@ -1,17 +1,13 @@
-
 #include <assert.h>
-#include <stddef.h>
-#include <errno.h>
-void do_more_stuff(char *ptr) {
-    assert(ptr != NULL);
-}
 
-void do_stuff() {
-    do_more_stuff(NULL);
+int factorial(int n) {
+    assert(n >= 0);
+    if(n == 0) return 1;
+    return n*factorial(n-1);
 }
 
 int main() {
-    errno = 0;
-    assert(2+2 == 4);
-    do_stuff();
-}
+    printf("Factorial of %d is %d\n", 10, factorial(10));
+    printf("Factorial of %d is %d\n", -1, factorial(-1));
+    return 0;
+}
\ No newline at end of file