Documentation for User.set_unusable_password() doesn't feel complete

[Brice PARENT]

When you set an usable password (using https://docs.djangoproject.com/en/dev/ref/contrib/auth/#django.contrib.auth.models.User.set_unusable_password), it is not really clear that to make the password usable again, one should use `set_password` and define a new one.
The doc says that this method "Marks the user as having no password set." which sounds like it's a boolean attribute somewhere that we might unset somehow. It should probably state that the method replaces the active password by one that can never be used, and add that to be able to use the password, it has to be set again using `set_password`. It also gives the false impression that we could prevent temporarily an user from login by setting this, but that would be a bad idea as it would lose the password.

Or maybe the method name `set_unusable_password` is explicit enough in english, but for other languages, I'm not sure the documentation should only rely on the methods names to be understood (the description looks like the one for a method that would be called `set_password_unusable`).

What do you think about it?
Thanks

[jorr...@gmail.com]

Does setting an unusable password on a user prevent them from using the reset password feature?

[Tim Graham]

Yes, there's a mention of that on the password_reset() view docs: https://docs.djangoproject.com/en/stable/topics/auth/default/#django.contrib.auth.views.password_reset

Feel free to submit some docs clarifications as a pull request if you'd like.