Match docs to the actual working implementation.


And add extended description of _why_