improved docstring and working examples