A: this feature is so difficult to understand and so easy to use incorrectly B: let's document it!