Improve documentation

Author: rexim

README.md

@@ -2,15 +2,37 @@
 
 Custom coroutines implementation in GNU C.
 
-## Supported platforms
+## What is a Coroutine?
 
-- Linux x86_64
+<!-- This is almost an exact copy of "What is a Coroutine?" section from ./examples/counter.c, but it's slightly modified to make more since on the front README page of a GitHub Repo -->
 
-*More are planned in the future*
+Coroutine is a lightweight user space thread with its own stack that can suspend its execution and switch to another coroutine on demand. Coroutines do not run in parallel but rather cooperatively switch between each other whenever they feel like it.
+
+Coroutines are useful in cases when all your program does majority of the time is waiting on IO. So with coroutines you have an opportunity to switch the context and go do something else. It is not useful to split up heavy CPU computations because they all going to be executed on a single thread. Use proper thread for that (pthreads on POSIX).
+
+Good uses case for coroutines are usually Network Applications and UI. Anything with a slow Async IO.
 
-## Quick Start
+<!-- End of the copy of the section -->
+
+See [coroutine.h](./coroutine.h) for more info. See [./examples/counter.c](./examples/counter.c) for a simple usage example in C.
+
+To build the example:
 
 ```console
 $ make
 $ ./build/counter
 ```
+
+There are actually much more examples in the [./examples/](./examples/) in a variety of languages. To build all of them do:
+
+```console
+$ make examples
+```
+
+Make sure you have all the corresponding compilers for the languages.
+
+## Supported platforms
+
+- Linux x86_64
+
+*More are planned in the future*

coroutine.h

@@ -1,6 +1,30 @@
 #ifndef COROUTINE_H_
 #define COROUTINE_H_
 
+// # What is a Coroutine?
+//
+// Coroutine is a lightweight user space thread with its own stack that can
+// suspend its execution and switch to another coroutine (see coroutine_yield()
+// function). Coroutines do not run in parallel but rather cooperatively switch
+// between each other whenever they feel like it.
+//
+// Coroutines are useful in cases when all your program does majority of the
+// time is waiting on IO. So with coroutines you have an opportunity to do
+// coroutine_yield() and go do something else. It is not useful to split up
+// heavy CPU computations because they all going to be executed on a single
+// thread. Use proper thread for that (pthreads on POSIX).
+//
+// Good uses case for coroutines are usually Network Applications and UI.
+// Anything with a slow Async IO.
+//
+// # How does it work?
+//
+// Each coroutine has its own separate call stack. Every time a new coroutine is
+// created with coroutine_go() a new call stack is allocated in dynamic memory.
+// The library manages a global array of coroutine stacks and switches between
+// them (on x86_64 literally swaps out the value of the RSP register) on every
+// coroutine_yield(), coroutine_sleep_read(), or coroutine_sleep_write().
+
 #ifdef __cplusplus
 extern "C" {
 #endif // __cplusplus
@@ -18,7 +42,9 @@ void coroutine_init(void);
 // the memory, and killing all the currently running coroutines.
 void coroutine_finish(void);
 
-// Switch to the next coroutine.
+// Switch to the next coroutine. The execution will continue starting from
+// coroutine_yield() (or any other flavor of it like coroutine_sleep_read() or
+// coroutine_sleep_write) call of another coroutine.
 void coroutine_yield(void);
 
 // Create a new coroutine. This function does not automatically switch to the
@@ -31,19 +57,23 @@ void coroutine_go(void (*f)(void*), void *arg);
 size_t coroutine_id(void);
 
 // How many coroutines are currently alive. Could be used by the main coroutine
-// to wait until all the "child" coroutines have died.
+// to wait until all the "child" coroutines have died. It may also continue from
+// the call of coroutine_sleep_read() and coroutine_sleep_write() if the
+// corresponding coroutine was woken up.
 size_t coroutine_alive(void);
 
 // Put the current coroutine to sleep until the non-blocking socket `fd` has
 // avaliable data to read. Trying to read from fd after coroutine_sleep_read()
 // may still cause EAGAIN, if the coroutine was woken up by coroutine_wake_up
-// before the socket became available for reading.
+// before the socket became available for reading. You may treat this function
+// as a flavor of coroutine_yield().
 void coroutine_sleep_read(int fd);
 
 // Put the current coroutine to sleep until the non-blocking socket `fd` is
 // ready to accept data to write. Trying to write to fd after
 // coroutine_sleep_write() may still cause EAGAIN, if the coroutine was woken up
-// by coroutine_wake_up before the socket became available for writing.
+// by coroutine_wake_up before the socket became available for writing. You may
+// treat this function as a flavor of coroutine_yield().
 void coroutine_sleep_write(int fd);
 
 // Wake up coroutine by id if it is currently sleeping due to