commit adcff8e8893bbebfc4f454593c06cc8a3d4f614f
Author: Lee Rowlands <lee.rowlands@previousnext.com.au>
Date:   Wed Jan 21 09:19:56 2015 +1000

    p34

diff --git a/core/modules/system/core.api.php b/core/modules/system/core.api.php
index b157391..7f6acd2 100644
--- a/core/modules/system/core.api.php
+++ b/core/modules/system/core.api.php
@@ -575,28 +575,8 @@
  * appropriately for their particular sites.
  *
  * @section sec_define Defining permissions
- * Modules define permissions via a $module.permissions.yml file. This file
- * 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: false
- * @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
+ * Modules define permissions via a $module.permissions.yml file. See
+ * \Drupal\user\PermissionHandler for documentation of permissions.yml files.
  *
  * @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
deleted file mode 100644
index 0c20cf5..0000000
--- a/core/modules/system/example.permissions.yml
+++ /dev/null
@@ -1,5 +0,0 @@
-# This is an example permissions.yml file only.
-Example permission:
-  title: 'Example title'
-  restrict access: false
-  description: 'Example description'
diff --git a/core/modules/user/src/PermissionHandler.php b/core/modules/user/src/PermissionHandler.php
index ea90619..2b629b0 100644
--- a/core/modules/user/src/PermissionHandler.php
+++ b/core/modules/user/src/PermissionHandler.php
@@ -16,15 +16,38 @@
 /**
  * Provides the available permissions based on yml files.
  *
- * To define permissions you can use a $module.permissions.yml file:
+ * To define permissions you can use a $module.permissions.yml file. This file
+ * 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.
  *
+ * 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
- * administer permissions:
- *   title: Administer permissions
+ * # The key is the permission machine name.
+ * administer filters:
+ *   title: 'Administer text formats and filters'
+ *   description: 'Define how text is handled by combining filters into text formats.'
  *   restrict access: false
- *   description: some description
+ *
+ * permission_callbacks:
+ *   - Drupal\filter\FilterPermissions::permissions
  * @endcode
  *
+ * Some notes:
+ * - Machine name of the permission is 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 filter.permissions.yml
+ * @see \Drupal\filter\FilterPermissions
  * @see user_api
  */
 class PermissionHandler implements PermissionHandlerInterface {