Clarified how contrib.auth picks a password hasher for verification.
@@ -48,12 +48,16 @@ you're not sure, you probably don't. If you do, please read on:
Django chooses the algorithm to use by consulting the
:setting:`PASSWORD_HASHERS` setting. This is a list of hashing algorithm
-classes that this Django installation supports. The first entry in this list
-(that is, ``settings.PASSWORD_HASHERS[0]``) will be used to store passwords,
-and all the other entries are valid hashers that can be used to check existing
-passwords. This means that if you want to use a different algorithm, you'll
-need to modify :setting:`PASSWORD_HASHERS` to list your preferred algorithm
-first in the list.
+classes that this Django installation supports.
+
+For storing passwords, Django will use the first hasher in
+:setting:`PASSWORD_HASHERS`. To store new passwords with a different algorithm,
+put your preferred algorithm first in :setting:`PASSWORD_HASHERS`.
+
+For verifying passwords, Django will find the hasher in the list that matches
+the algorithm name in the stored password. If a stored password names an
+algorithm not found in :setting:`PASSWORD_HASHERS`, trying to verify it will
+raise ``ValueError``.
The default for :setting:`PASSWORD_HASHERS` is::
