Issue #1037352 by David_Rothstein: clarified usage of 'warning' parameter.

1 files changed, 13 insertions, 6 deletions

diff --git a/modules/system/system.api.php b/modules/system/system.api.php
index 0981438c2..5ee776ae5 100644
--- a/modules/system/system.api.php
+++ b/modules/system/system.api.php
@@ -1908,12 +1908,19 @@ function hook_system_info_alter(&$info, $file, $type) {
  *     have inherent security risks across a variety of potential use cases
  *     (for example, the "administer filters" and "bypass node access"
  *     permissions provided by Drupal core). When set to TRUE, a standard
- *     warning message defined in user_admin_permissions() will be associated
- *     with the permission and displayed with it on the permission
- *     administration page. Defaults to FALSE.
- *   - warning: (optional) A translated warning message to display on the
- *     permission administration page. This warning overrides the automatic
- *     warning generated by 'restrict access' being set to TRUE.
+ *     warning message defined in user_admin_permissions() and output via
+ *     theme_user_permission_description() will be associated with the
+ *     permission and displayed with it on the permission administration page.
+ *     Defaults to FALSE.
+ *   - warning: (optional) A translated warning message to display for this
+ *     permission on the permission administration page. This warning overrides
+ *     the automatic warning generated by 'restrict access' being set to TRUE.
+ *     This should rarely be used, since it is important for all permissions to
+ *     have a clear, consistent security warning that is the same across the
+ *     site. Use the 'description' key instead to provide any information that
+ *     is specific to the permission you are defining.
+ *
+ * @see theme_user_permission_description()
  */
 function hook_permission() {
   return array(