Refactor: scheduler: best practices when checking node capacity

Add doxygen blocks for relevant functions, use bool instead of gboolean,
improve comments and log messages, and tweak formatting.