Refactor docs to provide stricter seperation between API and implemtation documention.

[elbenfreund]

Right now, our documentation mixes API reference with implementation details. This is a direct consequence of efforts to reconstruct the legacy API on the fly and storing this knowledge in a accessable way.

In order to provide clean an focused documentation however, it is preferable to be stricter about those differing documentation aspects.

• Docstrings shoudl provide a genreal API reference.
• (Block)comments are to provide implementation notes.