improve documentation

fixes #1391

and add improvements/fixes to documentation
`for y in Y` would be a little bit clearer.