Thanks for you comments. I've pushed an updated docstring. Please let me know if it's still not clear or if you think there's a better way to do it.