more docstrings and shell improvements