COSMIT: many cosmetic comments

Fixes remarks by @ogrisel, @agramfort, @larsman, @jnothman
FIX: fix failing doctest
DOC: link FeatureAgglomeration better to dim red