Earlier quoted context omitted.
which is still better than no advice at all. It's good to know there are bad practices out there, and the doc team should update the doc and show how to avoid bad practice.
I disagree. I will happily take docs, such as rust's docs or NaCl's docs, which don't ever mention the possible of md5summing a password, to docs where there are hundreds of comments recommending exactly that terrible practice. There are a practically infinite number of ways to do things wrong, and very few ways to do things right. Documenting the right way by exhaustively demonstrating the wrong ways is a fool's err…
I would wager that you won't find an obviously bad security practice like md5() the password in the PHP documentation comments that isn't voted way down.