added the missing xml comments to code & enabled 1591

Complements #229 

/cc @adamchester