update docs for clarity and conformance to upstream 4.4 rebase