Add documentation

Just added more documentation. To the README file, but also to the code
to explain some rational.

Signed-off-by: Konrad Reiche <konrad.reiche@gmail.com>