fixes #3001 and polish docs