Comments from @kbarbary

* Fix docs
* Try to return input shape more faithfully.  Add some unit tests
  of that behavior.