DOC: add docstring
WIP: finish on #2856
DOC: fix typo