revise & document

[richard-unterberg]

• code must be better documented
• implemented features and workaround better explained

-> readme