Refactor: pacemaker-based: best practices for construct_pam_passwd()

Add a doxygen block, and improve error checking, log messages, comments,
and formatting.

Previously, the function would allocate the reply, and then on error,
clear and free it. Now, it doesn't allocate the reply unless it will be
returned.