No information about format of permissions.yml in permissions topic

As we seem to need here is to add the documentation on core/modules/user/src/PermissionHandler and tag it somehow.
I kinda think that this is the right place to document it.

Most peopel would not need to care about the PermissionHandler class, and we have not used that philosophy when documenting other YML files, such as the links.*.yml files.

Well, sure, but it used to be the only sane place, given that previously this documentation used to be in hook_permission().

This issue, at lesat for me, is another example where a exmaple.permissions.yml would help.
Especially for people trying to find quick examples such a file is way more convenient that a defgroup somewhere.
At least from my point of view, not having to go to api.drupal.org is a good thing.

See #2323895-29: [Meta] Document format/content of various YML files

tagging as a task for today's critical office hours, good novice one

Tackling this for the #SprintWeekend2015.

.

It is not clear whether I will need a patch to add the example to the PermissionHandler but that will be my next step and then it can be used or not.

Here is what I propose for adding to https://api.drupal.org/api/drupal/core!modules!system!core.api.php/group... It is not clear to me how that will happen.

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:

administer filters:
  title: 'Administer text formats and filters'
  description: 'Define how text is handled by combining filters into text formats.'
  restrict access: true

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

I sorted out how this type of patch happens but it is my first try at something like this.

I added an example from the filter.permissions.yml to the core.api.php with some comments.

Then I tried to add a reference to the PermissionsHandler class which already has an example in it.

documenting some things from our irc conversation.

1. +++ b/core/modules/system/core.api.php
   @@ -576,9 +576,28 @@
   + * - machine name of the permission required to visit the URL.
   

   I dont think a URL is always going to be associated.

2. +++ b/core/modules/system/core.api.php
   @@ -576,9 +576,28 @@
   + * - title is the human readable information appearing in the Permissions page.
   

   "information" sounds more comprehensive. I think it is just a human readable name.

3. +++ b/core/modules/system/core.api.php
   @@ -576,9 +576,28 @@
   + * - When "restrict access" is set to "true" a warning about site security will
   + * be displayed on the Permissions page.
   + * - description is optional
   

   let's make each item in the list a sentence or a phrase, but dont mix the two kinds in the same list.

4. +++ b/core/modules/user/src/PermissionHandler.php
   @@ -24,6 +24,8 @@
   + * @see user_api
   

   ah, I see this is the def group where the more detail is being added. ok.

Reformated to https://www.drupal.org/node/1354#lists standards for lists and corrected a typo.

Looking good. I've just got one comment.

+++ b/core/modules/user/src/PermissionHandler.php
@@ -24,6 +24,8 @@
+ * * @defgroup user_api User accounts, permissions, and roles

I think this might be the wrong use of @defgroup. The topic is already defined in core.api.php in the same block of code that you edited above.

If you're trying to make it so that a link to PermissionHandler.php's docblock displays under the @defgroup topic I think you want to use @ingroup here.

You can find more on the use of @defgroup and @ingroup here: https://www.drupal.org/coding-standards/docs#defgroup

Also, you've got two "*" there, that should be just one for sure.

Thx for the feedback eojthebrave.

I was simply trying to make sure the PermissionHandler information was completed out by the information available in the core User_api documention. I initally simply used @see user_api and this may accomplish what I was trying to do.

And that is what I get for creating the patch late at night. I actually removed the extra * in this one.

looking better!

1. +++ b/core/modules/system/core.api.php
   @@ -576,9 +576,28 @@
   + * Here is an example from the core filter module:
   + *
   + * @code
   + * administer filters:
   ...
   + * @endcode
   + *
   + * Some notes:
   

   https://www.drupal.org/node/1354#code

   says
   " Do not use a blank line between the text that explains the code sample and the code sample itself."
   check the example there.

2. +++ b/core/modules/system/core.api.php
   @@ -576,9 +576,28 @@
   + *   title: 'Administer text formats and filters'
   + *   description: 'Define how text is handled by combining filters into text
   + *   formats.'
   + *   restrict access: true
   

   in core/modules/filter/filter.permissions.yml that description line is not wrapped.

   Since this is a code snippit, dont wrap it. It is not wrapped in the code.

3. +++ b/core/modules/system/core.api.php
   @@ -576,9 +576,28 @@
   + * - Description is optional.
   +
     *
   

   oops. a blank line in the the doc block.

+++ b/core/modules/user/src/PermissionHandler.php
@@ -24,6 +24,8 @@
+ * @ingroup user_api User accounts, permissions, and roles

I'm not sure if this should be @ingroup or @see. But I know It should not have the "User accounts, ....roles" part.

See example in https://www.drupal.org/node/1354#defgroup

[edit:]
Since this doc block has information that duplicates that being added to the user_api defgroup, I think this would be better as an @see like you had it before.

I still think, that you also want a examples.permissions.yml or similar, so you can just c&p an existing example and be done with it

Where would an examples.permissions.yml go in the file structure? Should I provide it as a seperate patch?

And does this make sense?

Example permission:
  title: 'Example title'
  restrict access: true
  description: 'Example description'

Thanks for the help YesCT. I have changed the spacing. And I have moved @ingroup to @see which I think was jhodgden's original intent.

oops. Looks like some unrelated changes got in.

please make a new patch without those changes.

Fixes #18, #19, #20
Hoping the presence of an example.permissions.yml doesn't show up anywhere.

Thanks for the patch cleanup larowlan. The inclusion of the example.permissions.yml in core/modules/system makes sense to me.

Thanks @apratt and @larowlan. As per #5, @alexpott, @catch, @effulgentsia, @webchick, and I agreed that this issue should be critical because of the security implications.

+++ b/core/modules/system/core.api.php
@@ -576,9 +576,27 @@
+ * 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

I'd rather go with restrict access: false as this is the default, isn't it?

why not

Thank you

+++ b/core/modules/system/core.api.php
--- /dev/null
+++ b/core/modules/system/example.permissions.yml

+++ 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: false
+  description: 'Example description'

I don't think we should be creating this file. This will create problems for a custom or contrib module called example. Let's drop it from this patch and create a non critical follow up to think about where and which yml files we should have examples of.

Agreed that adding a real example is strange, especially inside system.module? That would not actually conflict I think, but it is more confusing that helpful IMHO.

What if we just refer to an existing, real file as an example? filter.permissions.yml looks like a great example to me, just one permission, but almost everything covered, including restrict access and a permission callback.

and a permission callback.

Which, by the way, is not documented here yet?

Fixes #31 through #34
interdiff.callbacks.txt contains just the new hunks relating to callbacks.

Looks good, just think about dynamic permissions which are briefly described OTOH they are special case.
PS: patch needs to check grammar

I moved the "some notes" content that was below the code sample to be inline comments in the code sample. I think this is easier to read, and easier to relate the note the the key in question.

Great!

This issue addresses a critical bug and is allowed per https://www.drupal.org/core/beta-changes. Committed 165cd55 and pushed to 8.0.x. Thanks!