implement suggestion #199

Tentative pull. functional, with doc and test.
The usage line here doesn't match the method being documented.