docs(core): improve documentation.

Closes #1526
Closes #1525