Refactor: scheduler: best practices for set_role_promoted()

Rename to set_next_role_promoted() for consistency with
set_next_role_unpromoted(), and add a doxygen block