EntityTypeInterface::getGroup() doesn't explain what the group is

Is this useful? Should we deprecate this? It doesn't seem to be used anywhere in core:

$ egrep -r 'getGroup\(' core
core/tests/Drupal/Tests/Core/Menu/ContextualLinkDefaultTest.php:    $this->assertEquals($group_name, $this->contextualLinkDefault->getGroup());
core/modules/breakpoint/tests/src/Unit/BreakpointTest.php:    $this->assertEquals('Breakpoint', $this->breakpoint->getGroup());
core/modules/breakpoint/src/Breakpoint.php:  public function getGroup() {
core/modules/breakpoint/src/BreakpointInterface.php:  public function getGroup();
core/lib/Drupal/Core/Entity/EntityType.php:  public function getGroup() {
core/lib/Drupal/Core/Entity/EntityTypeInterface.php:  public function getGroup();
core/lib/Drupal/Core/TypedData/Validation/ExecutionContext.php:  public function getGroup() {
core/lib/Drupal/Core/Menu/ContextualLinkDefault.php:  public function getGroup() {
core/lib/Drupal/Core/Menu/ContextualLinkInterface.php:  public function getGroup();

In contextual links, breakpoints and execution contexts "group" means a different thing, so as far as I can see this isn't actually used anywhere; I think we perhaps are better off using interfaces to identify this sort of thing.

The same question was asked in #2549017-2: Add getGroup() and getGroupLabel() to an interface and add docs when it was first introduced.

Group *labels* are useful as per #2116551: Fix the UX of Entity Reference fields

Adding some tags to shed some light on this good novice/first issue

group is the value passed in the annotation for that entity type, which means that the values set by Drupal core are only a restrict set of possible values. They can be given as example, but the documentation should not make users think those are the only possible values.

The following interface properties should also be better documented.

  /**
   * The machine name of the entity type group.
   *
   * @var string
   */
  protected $group;

  /**
   * The human-readable name of the entity type group.
   *
   * @var string|\Drupal\Core\StringTranslation\TranslatableMarkup
   *
   * @see \Drupal\Core\Entity\EntityTypeInterface::getGroupLabel()
   */
  protected $group_label;

At least, the first property should contain a reference to the interface method, if its documentation is going to explain what an entity type group is.

  /**
   * The machine name of the entity type group.
   *
   * @var string
   *
   * @see \Drupal\Core\Entity\EntityTypeInterface::getGroup()
   */
  protected $group;

Rerunning tests. Though I'm 99% they were random failures.

Yup random failures.

Reviewed the changes and now understand what entity groups are! haha

Looks great to me now.

Good to see this being documented. I made a thorough read this time and have made some suggestion and I have some questions.

I re-read the changes and I think they are clear, correct and follow our standards. Back to RTBC

Committed and pushed 817c02e84c to 10.1.x and 903768e429 to 10.0.x and 46f4d42d9a to 9.5.x. Thanks!

As a documentation improvement I backported this to 9.5.x