I think an example in the doc string would make this clearer