Update docs for changes proposed in #2684