Addressing more of Marten's comments:
especially an improved docstring.

have yet to write an explicit example...