diff --git a/core/modules/user/user.api.php b/core/modules/user/user.api.php
index d4a093e362216ca626601814355f34884a8a9c43..2f40eb90b46fdcbda3e395363978fdb0c10dbeef 100644
--- a/core/modules/user/user.api.php
+++ b/core/modules/user/user.api.php
@@ -109,13 +109,16 @@ function hook_user_cancel_methods_alter(&$methods) {
  * that is displayed. Can be used to ensure user privacy in situations where
  * $account->getDisplayName() is too revealing.
  *
- * @param string $name
- *   The string that $account->getDisplayName() will return.
- *
- * @param $account
- *   The account object the name belongs to.
+ * @param string|Drupal\Component\Render\MarkupInterface $name
+ *   The username that is displayed for a user. If a hook implementation changes
+ *   this to an object implementing MarkupInterface it is the responsibility of
+ *   the implementation to ensure the user's name is escaped properly. String
+ *   values will be autoescaped.
+ * @param \Drupal\Core\Session\AccountInterface $account
+ *   The user object on which the operation is being performed.
  *
  * @see \Drupal\Core\Session\AccountInterface::getDisplayName()
+ * @see sanitization
  */
 function hook_user_format_name_alter(&$name, $account) {
   // Display the user's uid instead of name.