added comments, move example to docstring