some more thorough documentation for #614