fix doc following @charettes comments