Refactor: scheduler: best practices when comparing node capacities

Rename compare_capacity() to pcmk__compare_node_capacities(), and reimplement
to use a single function (instead of two) to compare a utilization attribute.

Also add doxygen blocks to the functions, and use g_hash_table_lookup() instead
of unnecessarily using the more complicated equivalent call to
g_hash_table_lookup_extended().