Refactor: scheduler: best practices for promotable_colocation_rh()

Rename promotable_colocation_rh() to
pcmk__update_promotable_dependent_priority() for readability (a shorter name
would be nice but ...), move its declaration to library-private header,
add a doxygen block, drop a redundant argument, and improve variable names,
log messages, comments, and formatting.