updated readme with more usage
updated docstrings in core