update docs and and changelog for #612 (#639)

* update docs and and changelog for #612

* update changelog

* more detail
2 files changed