Improve documentation

This commit adds comments to explain some non-obvious behavior, for the
sake of completion.