Clarify a few points of documentation. Fixes #1475.

[ci skip]