civicrm_hook_alterMailParams does not describe important quirks

Created by: artfulrobot

The docs don't explain how to add custom headers, nor do they point out that this hook might be called twice on one email in certain contexts, nor does it allow for flexmailer.

PR coming.