Improve documentation of EntityTypeInterface label functions

Thank you @alex to create the follow up

https://www.drupal.org/files/issues/interdiff_19999.txt already contains an interdiff for it.

+   * This label should be used to refer to a list of entities.

I thought so too, until I recently wanted to write a patch to auto-generate a collection route for entities. The problem is that the plural label as currently returned by the method is in fact lowercase, so it's not suitable for a page title of a page that lists entities.

So I guess we need another method :-/ not sure...

At the very least the docs need to explain the situation better.

Opened #2767025: Add entity type label for a collection of entities for #5. #6 is still valid, IMHO, though.

Minor nitpick, but the descriptions aren't consistent at the moment.

1. +++ b/core/lib/Drupal/Core/Entity/EntityTypeInterface.php
   @@ -617,6 +617,9 @@ public function getDataTable();
   +   * This method should be used when you want to refer to the abstract concept
   

   This label

2. +++ b/core/lib/Drupal/Core/Entity/EntityTypeInterface.php
   @@ -627,12 +630,16 @@ public function getLabel();
   +   * This method should be used when you refer to exactly one entity.
   

   This label

I also agree with tstoeckler about the collection label.

Discussed with @alexpott, @cilefen, @fago, @Berdir, and @amateescu awhile back and we agreed this issue is not a major bug -- it looks like it was filed as such by accident.

Still an issue, though. Maybe a novice contributor could try to start addressing the recent feedback on the issue?

Adding patch. Tried to make the descriptions consistent.

I think this is a great start! I think it would be incredibly helpful to include an example usage with all of the methods, though. Not sure if others agree, so leaving at needs review.

Since there has been a version change, the patch by @gianani (#12) did not apply so I did a partial apply and manually applied the rest. (First patch submitted to core here, so please let me know if this should be handled another way.)

As requested by @tstoeckler I added examples to getSingularLabe(), getPluralLabel(), and getCountLabel(). I also adjusted the descriptions in those functions to match the descriptions of the corresponding protected variables in EntityType.php.

Thanks @brathbone for pushing this forward. I have some comments but I think we're pretty close, I really like the examples you added!

1. +++ b/core/lib/Drupal/Core/Entity/EntityTypeInterface.php
   @@ -643,7 +648,12 @@ public function getLowercaseLabel();
      public function getCollectionLabel();
   

   We should add docs for the new collection label, as well.

2. +++ b/core/lib/Drupal/Core/Entity/EntityTypeInterface.php
   @@ -643,7 +648,12 @@ public function getLowercaseLabel();
   +   * 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).
   

   Thanks for adding this! It's not quite correct, though, I think. The singular label would be "opportunity" and not "Opportunity" (i.e lowercase).

   I also think adding quotes will help make the text clearer.

3. +++ b/core/lib/Drupal/Core/Entity/EntityTypeInterface.php
   @@ -651,7 +661,12 @@ public function getCollectionLabel();
   +   * 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.)
   

   Same as above, should be lowercase.

4. +++ b/core/lib/Drupal/Core/Entity/EntityTypeInterface.php
   @@ -659,7 +674,13 @@ public function getSingularLabel();
   +   * Gets the definite article form of the name of the entity type, to be used
   +   * with a specific quantity or count of entities.
   

   We should still have a one-line summary, although I agree that the current "count label" can definitely be improved.

5. +++ b/core/lib/Drupal/Core/Entity/EntityTypeInterface.php
   @@ -659,7 +674,13 @@ public function getSingularLabel();
   +   * 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”
   

   Same as above, this should be lowercase as well.

Thanks to you, @tstoeckler, for the feedback. This new patch and interdiff contains the changes you requested:

-I added more documentation to getCollectionLabel(). I based this off of issue 2767025 and specifically the "Problem/Motivation" section.
-I adjusted all the examples to be lowercase and contained in quotation marks.
-I adjusted to the first line of the getCountLabel() documentation to fit into a single line.

Happy to adjust anything else.

Thanks a lot @brathbone, I think it reads very nicely now. You will save a lot of future developers from a lot of confusion with you work on this issue, this should not be underestimated! Very cool.

RTBC+1 from my side.

Anyone else seeing weird characters in the patch?

For example: “1 opportunity”, “5 opportunities”, “1 child”,
+   * “6 children”, “1 content item”, “25 content items”

@kristiaanvandeneynde - No, we are not seeing these weird characters in this patch. we are seeing like this below mentioned.

For example: “1 opportunity”, “5 opportunities”, “1 child”,
   * “6 children”, “1 content item”, “25 content items”

Oh, I didn't notice that you used actual proper quote characters. Not sure if that's allowed in in-code documentation. (Not saying that it's not, I genuinely don't know.) So moving back to needs review.

Yeah they need to be double quotes. Any special character should -AFAIK- be HTML-encoded such as “ and ”. Seeing as that can't be done in comments, those should be regular double quotes.

Nice!

+++ b/core/lib/Drupal/Core/Entity/EntityTypeInterface.php
@@ -631,11 +634,18 @@ public function getLabel();
+   * @see ::getLabel().

This should have the full namespace even though it's the same class (and no period). I've fixed this on commit.

Committed to 8.4.x. Since this is a documentation improvement, it's also eligible during the 8.3.x RC phase, so I've cherry-picked the patch to 8.3.x as well.