diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php
index 3ffb004..212d247 100644
--- a/core/modules/system/core.api.php
+++ b/core/modules/system/core.api.php
@@ -576,9 +576,28 @@
  *
  * @section sec_define Defining permissions
  * Modules define permissions via a $module.permissions.yml file. This file
- * defines machine names, human-readable names, and optionally
- * descriptions for each permission type. The machine names are the canonical
- * way to refer to permissions for access checking.
+ * defines machine names, human-readable names, restrict access (if required for
+ * security warning) and optionally descriptions for each permission type. The
+ * machine names are the canonical way to refer to permissions for access
+ * checking.
+ *
+ * Here is an example from the core filter module:
+ *
+ *  * @code
+ * administer filters:
+ *   title: 'Administer text formats and filters'
+ *   description: 'Define how text is handled by combining filters into text
+ * formats.'
+ *   restrict access: true
+ * @endcode
+ *
+ * Some notes:
+ * - machine name of the permission required to visit the URL.
+ * - title is the human readable information appearing in the Permissions page.
+ * - When "restrict access" is set to "true" a warning about site security will
+ * be displayed on the Permissions page.
+ * - description is optional
+
  *
  * @section sec_access Access permission checking
  * Depending on the situation, there are several methods for ensuring that
diff --git a/core/modules/user/src/PermissionHandler.php b/core/modules/user/src/PermissionHandler.php
index d41b05e..d576cdd 100644
--- a/core/modules/user/src/PermissionHandler.php
+++ b/core/modules/user/src/PermissionHandler.php
@@ -24,6 +24,8 @@
  *   restrict access: true
  *   description: some description
  * @endcode
+ *
+ * @see user_api
  */
 class PermissionHandler implements PermissionHandlerInterface {