hook_permission is missing doc about 'warning'

Not really:

       $perm_item += array(
          'description' => '', 
          'restrict access' => FALSE, 
          'warning' => !empty($perm_item['restrict access']) ? t('Warning: Give to trusted roles only; this permission has security implications.') : '',
        );
 

The code is generating a warning from the 'restrict access' field from hook_permission(), which is correctly documented in hook_permission() docs.

Ah, OK. Yes that should be documented in hook_permission.

Here's a patch.

the patch works correctly - looks good

Needs to go to d8 and then d7

Committed to 8.x. Thanks.

Committed to 7.x. Thanks!

I guess it was a mistake not to document this parameter at all... but I think we really really want to discourage people from using it.

The idea is that this is supposed to be a clear, standard warning that is constant across all permissions, not a place for people to dump things that actually belong in the permission description. I can think of very few (if any) situations where it would be a good idea to set this.

Here's one approach to deal with this via the documentation (attached).

I think it might actually be preferable to just take away the ability to set this altogether (you can still change the text globally for all permissions via the theme system, e.g. using a preprocess function, which is a legitimate thing to do). But since this is an issue in the documentation queue, I'm starting with a documentation patch :)

I'm on board with this idea, and the patch wording seems fine to me.
Should go into 8.x and 7.x.

Committed to 8.x. Moving to D7. Probably needs work as both patches will have to be merged.

The original patch was already committed to D7, so #9 should apply fine there as well.

However, first we have to fix the conflicts that were introduced in D8...

Sorry about that. Committed #12 to my local 8.x tree, and will commit the changes shortly. Moving back to 7.x. Thanks David.

Poor testbot. #9 is the one that's RTBC for Drupal 7.

Committed #9 to 7.x. Thanks!