> It looks like better documentation could have prevented this bug.
Where?
Barring user-submitted comments, PHP has consistently had some of the most complete programming language documentation.
This exact issue is specifically documented with the mail() function[1] so I'm not sure you can blame PHP or ask for better documentation in this case:
"This parameter is escaped by escapeshellcmd() internally to prevent command execution. escapeshellcmd() prevents command execution, but allows to add additional parameters. For security reasons, it is recommended for the user to sanitize this parameter to avoid adding unwanted parameters to the shell command."
Escaping too many times or incorrectly is a pretty common error but it's normally of the PEBKAC variety.