Feature/update readme

Made use of markdown more consistent,
Improved code examples,
Fixed one line where `public static` was used instead of `protected`.