code cleanup
more clarity in doc + extra test to prove it