diff --git a/core/modules/user/src/PermissionHandler.php b/core/modules/user/src/PermissionHandler.php
index b51cd85..2b629b0 100644
--- a/core/modules/user/src/PermissionHandler.php
+++ b/core/modules/user/src/PermissionHandler.php
@@ -22,6 +22,11 @@
  * machine names are the canonical way to refer to permissions for access
  * checking.
  *
+ * If your module needs to define dynamic permissions you can use the
+ * permission_callbacks key to declare a callable that will return an array of
+ * permissions, keyed by machine name. Each item in the array can contain the
+ * same keys as an entry in $module.permissions.yml.
+ *
  * Here is an example from the core filter module (comments have been added):
  * @code
  * # The key is the permission machine name.
@@ -29,6 +34,9 @@
  *   title: 'Administer text formats and filters'
  *   description: 'Define how text is handled by combining filters into text formats.'
  *   restrict access: false
+ *
+ * permission_callbacks:
+ *   - Drupal\filter\FilterPermissions::permissions
  * @endcode
  *
  * Some notes:
@@ -39,6 +47,7 @@
  * - Description is optional.
  *
  * @see filter.permissions.yml
+ * @see \Drupal\filter\FilterPermissions
  * @see user_api
  */
 class PermissionHandler implements PermissionHandlerInterface {