ticket:10107: improve API docs for new function


git-svn-id: http://source.icu-project.org/repos/icu/icu@33540 251d0590-4201-4cf1-90de-194747b24ca1