DOC comment from @amueller + several minor improvements