Fix773

Fixes issue#773 + add documentation + add exhaustive tests.
Does not fix issue#774 however. I think we need a meeting for that.
you're right.. sounds strange to me but it's fine.