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.
Merge pull request #2964 from certik/doc2542

DOC: document the casting rules changes