Issue #3367439: Add proper documentation for entity type's admin_permission and collection_permission

core/lib/Drupal/Core/Entity/EntityType.php

@@ -76,6 +76,15 @@ class EntityType extends PluginDefinition implements EntityTypeInterface {
   /**
    * The name of the default administrative permission.
    *
+   * This permission must be declared by the module providing the entity type.
+   * Users with the administrative permission can perform create, view, update
+   * or delete operations on any entity of that type. They also are granted
+   * access to the overview (or collection) of the entities of that type, if one
+   * exists.
+   *
+   * If a custom access control handler is declared, access can be restricted
+   * even for users with this permission.
+   *
    * @var string
    */
   // phpcs:ignore Drupal.NamingConventions.ValidVariableName.LowerCamelName, Drupal.Commenting.VariableComment.Missing
@@ -84,6 +93,19 @@ class EntityType extends PluginDefinition implements EntityTypeInterface {
   /**
    * The name of the collection permission.
    *
+   * This permission must be declared by the module providing the entity type.
+   * Users with the collection permission are allowed to access the overview (or
+   * collection) of the entities of that type, if one exists. It does not grant
+   * access to any particular entities, but is used in combination with other
+   * permissions. For example. this makes it possible to grant users access to
+   * view entities of a particular type in the overview, but not edit or delete
+   * them. Another example is to grant users access to manage certain entities
+   * from the overview, but not all entities.
+   *
+   * If a custom access control handler is declared, access can be restricted
+   * even further for users with this permission or, alternatively, further
+   * access can be granted.
+   *
    * @var string
    */
   // phpcs:ignore Drupal.NamingConventions.ValidVariableName.LowerCamelName, Drupal.Commenting.VariableComment.Missing

[Joachim Noreiko]

I'm not keen on this wording. It makes it sound like something called an 'overview' of entities might also exist, which is different from the collection.

Also, we don't use the word 'overview' in the entity system AFAICT.

The EntityListBuilderInterface class calls them 'entity listings', and lots of other thing calls it the collection.

To avoid tautology here, I'd just say 'the entity listing'.

[Joachim Noreiko]

Same as above.

If we want to give more detail here, we could say something like 'the entity listing defined by the 'collection' entity route and link template..

[Joachim Noreiko]

s/./,/ after 'example'.

[Joachim Noreiko]

I also find these examples a bit confusing.

And, nitpick: for more than one example, I would bullet list them for clarity.