Issue #2701005 by brathbone, gaurav.kapoor, gianani, alexpott, tstoeckler, kristiaanvandeneynde, Yogesh Pawar: Improve documentation of EntityTypeInterface label functions

2 files changed, 39 insertions, 4 deletions

diff --git a/core/lib/Drupal/Core/Entity/EntityType.php b/core/lib/Drupal/Core/Entity/EntityType.php
index f9555a8..b39fb3f 100644
--- a/core/lib/Drupal/Core/Entity/EntityType.php
+++ b/core/lib/Drupal/Core/Entity/EntityType.php
@@ -172,6 +172,8 @@ class EntityType extends PluginDefinition implements EntityTypeInterface {
    * The human-readable name of the type.
    *
    * @var string
+   *
+   * @see \Drupal\Core\Entity\EntityTypeInterface::getLabel()
    */
   protected $label = '';
 
@@ -179,6 +181,8 @@ class EntityType extends PluginDefinition implements EntityTypeInterface {
    * The human-readable label for a collection of entities of the type.
    *
    * @var string
+   *
+   * @see \Drupal\Core\Entity\EntityTypeInterface::getCollectionLabel()
    */
   protected $label_collection = '';
 
@@ -186,6 +190,8 @@ class EntityType extends PluginDefinition implements EntityTypeInterface {
    * The indefinite singular name of the type.
    *
    * @var string
+   *
+   * @see \Drupal\Core\Entity\EntityTypeInterface::getSingularLabel()
    */
   protected $label_singular = '';
 
@@ -193,6 +199,8 @@ class EntityType extends PluginDefinition implements EntityTypeInterface {
    * The indefinite plural name of the type.
    *
    * @var string
+   *
+   * @see \Drupal\Core\Entity\EntityTypeInterface::getPluralLabel()
    */
   protected $label_plural = '';
 
@@ -202,6 +210,8 @@ class EntityType extends PluginDefinition implements EntityTypeInterface {
    * Needed keys: "singular" and "plural".
    *
    * @var string[]
+   *
+   * @see \Drupal\Core\Entity\EntityTypeInterface::getCountLabel()
    */
   protected $label_count = [];
 
diff --git a/core/lib/Drupal/Core/Entity/EntityTypeInterface.php b/core/lib/Drupal/Core/Entity/EntityTypeInterface.php
index 210c2dd..c8a28b4 100644
--- a/core/lib/Drupal/Core/Entity/EntityTypeInterface.php
+++ b/core/lib/Drupal/Core/Entity/EntityTypeInterface.php
@@ -621,6 +621,9 @@ interface EntityTypeInterface extends PluginDefinitionInterface {
   /**
    * Gets the human-readable name of the entity type.
    *
+   * This label should be used to present a human-readable name of the
+   * entity type.
+   *
    * @return string
    *   The human-readable name of the entity type.
    */
@@ -631,11 +634,18 @@ interface EntityTypeInterface extends PluginDefinitionInterface {
    *
    * @return string
    *   The lowercase form of the human-readable entity type name.
+   *
+   * @see \Drupal\Core\Entity\EntityTypeInterface::getLabel()
    */
   public function getLowercaseLabel();
 
   /**
-   * Gets the collection label of the entity type.
+   * Gets the uppercase plural form of the name of the entity type.
+   *
+   * This should return a human-readable version of the name that can refer
+   * to all the entities of the given type, collectively. An example usage of
+   * this is the page title of a page devoted to a collection of entities such
+   * as "Workflows" (instead of "Workflow entities").
    *
    * @return string
    *   The collection label.
@@ -643,7 +653,12 @@ interface EntityTypeInterface extends PluginDefinitionInterface {
   public function getCollectionLabel();
 
   /**
-   * Gets the singular label of the entity type.
+   * Gets the indefinite singular form of the name of the entity type.
+   *
+   * This should return the human-readable name for a single instance of
+   * the entity type. For example: "opportunity" (with the plural as
+   * "opportunities"), "child" (with the plural as "children"), or "content
+   * item" (with the plural as "content items").
    *
    * @return string
    *   The singular label.
@@ -651,7 +666,12 @@ interface EntityTypeInterface extends PluginDefinitionInterface {
   public function getSingularLabel();
 
   /**
-   * Gets the plural label of the entity type.
+   * Gets the indefinite plural form of the name of the entity type.
+   *
+   * This should return the human-readable name for more than one instance of
+   * the entity type. For example: "opportunities" (with the singular as
+   * "opportunity"), "children" (with the singular as "child"), or "content
+   * items" (with the singular as "content item").
    *
    * @return string
    *   The plural label.
@@ -659,7 +679,12 @@ interface EntityTypeInterface extends PluginDefinitionInterface {
   public function getPluralLabel();
 
   /**
-   * Gets the count label of the entity type
+   * Gets the label's definite article form for use with a count of entities.
+   *
+   * This label should be used when the quantity of entities is provided. The
+   * name should be returned in a form usable with a count of the
+   * entities. For example: "1 opportunity", "5 opportunities", "1 child",
+   * "6 children", "1 content item", "25 content items".
    *
    * @param int $count
    *   The item count to display if the plural form was requested.