Small refactoring and improved docs.

1 files changed, 15 insertions, 11 deletions

diff --git a/docs/ccommon_api.md b/docs/ccommon_api.md
index f26d55b7..93f46bf4 100644
--- a/docs/ccommon_api.md
+++ b/docs/ccommon_api.md
@@ -4,11 +4,14 @@ The following handy macros are safe to use, i.e. have no side-effects.
 
 ### c_forvar, c_fordefer, c_forbuffer
 General ***defer*** mechanics for resource acquisition. These macros allows to specify the release of the
-resource where the resource acquisition is made. This ensures that resources are released after usage.
+resource near the resource acquisition, and makes it easier to verify that resources will be released.
 
 **Note**: These macros are one-time executed **for**-loops. ***Only*** use `continue` in order to break out
 of a `c_forvar` / `c_fordefer`-block. ***Do not*** use `return`, `goto` or `break`, as it will prevent the
-`release`-statement to be executed at the end. The same applies for `c_forbuffer`.
+`release`-statement to be executed at the end. The same applies for `c_forbuffer`. This is not particular to
+the `c_for*()` macros, as one must always make sure to unwind temporary allocated resources before `return` in C.
+
+The **c_forbuffer** uses stack memory if buffer is <= to 256 bytes, othewise it uses the slower heap memory.
 
 | Usage                            | Description                                       |
 |:---------------------------------|:--------------------------------------------------|
@@ -16,14 +19,15 @@ of a `c_forvar` / `c_fordefer`-block. ***Do not*** use `return`, `goto` or `brea
 | `c_fordefer (release...)`        | Defer execution of `release` to end of block      |
 | `c_forbuffer (buf, type, n)`     | Declare, allocate and free memory buffer          |
 
-The `acquire`argument must be of the form: `type var = GetResource`. Note that the `release` argument can be 
-a list of statements enclosed in parathesises. `c_forvar` can handle multiple variables of same type by using
-the `c_arg` macro: `c_forvar (c_arg(cstr s1 = cstr_lit("Hello"), s2 = cstr_lit("world"), cstr_del(&s1), cstr_del(&s2))`.
-
-**c_forbuffer** uses stack memory if buffer is <= to 256 bytes, othewise it uses the slower heap memory.
-
+The `acquire`argument must be of the form: `type var = GetResource`. For multiple variables, use multiple
+`c_forvar` in sequence, or if variables are of same type, the `c_arg` macro can be used:
+```
+c_forvar (c_arg(cstr s1 = cstr_lit("Hello"), s2 = cstr_lit("world")), cstr_del(&s1), cstr_del(&s2))
+{
+}
+```
+**Example**: Load each line of a text file into a vector of strings:
 ```c
-// Example: Load each line of a text file into a vector of strings
 #include <errno.h>
 #include <stc/cstr.h>
 #include <stc/cvec.h>
@@ -119,5 +123,5 @@ c_del(cstr, &a, &b);
 Memory allocator for the entire library. Macros can be overloaded by the user.
 
 ### c_swap, c_arraylen
-- **c_swap(type, x, y)**: Simple macro for swapping internals of two objects. 
-- **c_arraylen(array)**: Return number of elements in an array, e.g. `int array[] = {1, 2, 3, 4};` 
+- **c_swap(type, x, y)**: Simple macro for swapping internals of two objects.
+- **c_arraylen(array)**: Return number of elements in an array, e.g. `int array[] = {1, 2, 3, 4};`