Improve documentation

Better documentation, including an important note about the behavior