Document the public API

[bmuenzenmeyer]

part of #603

basically, the scope of this issue is to properly document the public API

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[bmuenzenmeyer]

updated the OP