Added howto in docs and updated comments/docstrings to make them clear