Improve documentation for the core API

Currently, the core api is only poorly documented. This should be improved for all languages include python (see !363 (merged) )