core: documentation: updated, improved, and completed doxygen comments

Closes #948