diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php
index 3ffb004..d2e5bf7 100644
--- a/core/modules/system/core.api.php
+++ b/core/modules/system/core.api.php
@@ -576,9 +576,27 @@
  *
  * @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.
+ * - Title is the human readable name 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.
+ *
+ * @see example.permissions.yml
  *
  * @section sec_access Access permission checking
  * Depending on the situation, there are several methods for ensuring that
diff --git a/core/modules/system/example.permissions.yml b/core/modules/system/example.permissions.yml
new file mode 100644
index 0000000..d8306ed
--- /dev/null
+++ b/core/modules/system/example.permissions.yml
@@ -0,0 +1,5 @@
+# This is an example permissions.yml file only.
+Example permission:
+  title: 'Example title'
+  restrict access: true
+  description: 'Example description'
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 {