This amends c1141ed729b84f2c413975d37c1a91fb235fb14a; I failed to
update the doc-string after some design changes part-way through
developing the function.
Change-Id: Ifb83107153d1c3b5a9dbd0536a3d6ee1fe32922d
Reviewed-by: Jędrzej Nowacki <jedrzej.nowacki@qt.io>