fixed some phpdoc signatures and created some examples in folder examples/
merged readme.md after conflict