DOC: document the change in casting

This PR is based on #2962, i.e. the first patch is from it. The second patch is unique to this PR.