Doc block fixes

Hi Pablo,

let's try again, this is the pull request containing only the doc block fixes. Another for the code fixes - including unit tests where it makes sense - will follow.

Regards, Anton