little bit of work in the docstrings
cherry-picked commit by palli: f648a4b2d74e8b041ac8adace9060f664dba35f0