issue #7: docstrings for the core module