This docstring is the only one that the user will ever see.  It should be pretty comprehensive.  I suggest appending to the old docstring, currently residing in `dispatch_on_types`