improve doc as suggested by mvidner