DOC: document the casting rules changes

This does the work necessary for 1.7.x proposed in issues gh-561, gh-2542 and
gh-2685.