[Form] Document the hash_mapping option

Author: Seb33300

reference/forms/types/password.rst

@@ -35,6 +35,28 @@ with the ``value`` attribute set to its true value only upon submission.
 If you want to render your password field *with* the password value already
 entered into the box, set this to false and submit the form.
 
+``hash_mapping``
+~~~~~~~~~~~~~~~~
+
+**type**: ``string`` **default**: ``null``
+
+If set, the password will be hashed using the PasswordHasher component and
+stored in the specified property.
+
+Data passed to the form must be a ``PasswordAuthenticatedUserInterface`` object.
+
+.. caution::
+
+    To minimize the risk of leaking the plain password,
+    this option can only be used with the ``mapped`` option set to ``false``.
+
+        $builder->add('plainPassword', PasswordType::class, [
+            'hash_mapping' => 'password',
+            'mapped'       => false,
+        ]);
+
+    See the :ref:`"mapped" option documentation <reference-form-mapped>`.
+
 Overridden Options
 ------------------
 
@@ -81,6 +103,8 @@ The default value is ``''`` (the empty string).
 
 .. include:: /reference/forms/types/options/label_format.rst.inc
 
+.. _reference-form-mapped:
+
 .. include:: /reference/forms/types/options/mapped.rst.inc
 
 .. include:: /reference/forms/types/options/required.rst.inc