[TheDong]

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 errand.

But more to the point, I will happily take no docs at all to docs that are more wrong than right.

[jjeaff]

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.