EntityTypeBundleInfo::getBundleInfo() @return needs more detail

I'll try to work on this.

I'm looking into this at DrupalCon NOLA

Adding description.

Thanks, but...

+++ b/core/lib/Drupal/Core/Entity/EntityTypeBundleInfoInterface.php
@@ -22,7 +22,7 @@ public function getAllBundleInfo();
+   *   Returns an array of bundle ID .

I do not think this is accurate, according to the issue summary?

Done please review.

Giving it a try.

1. +++ b/core/lib/Drupal/Core/Entity/EntityTypeBundleInfoInterface.php
   @@ -22,7 +22,9 @@ public function getAllBundleInfo();
       * @return array
   

   So this is an array of arrays? Then the type should be "array[]".

2. +++ b/core/lib/Drupal/Core/Entity/EntityTypeBundleInfoInterface.php
   @@ -22,7 +22,9 @@ public function getAllBundleInfo();
   +   *   Returns an array of bundle information for an entity type.
   +   *   Format $bundles[BUNDLE_TYPE][ID] => [LABEL]
   +   *   Example: $bundles['comment']['label']
   

   Format is wrong, this should be $bundle_info[BUNDLE_NAME]['label'] => LABEL
   And the comment should say: "If the entity type does not have bundles then BUNDLE_TYPE is the entity type."

3. +++ b/core/modules/help/help.api.php
   @@ -48,7 +48,7 @@ function hook_help($route_name, \Drupal\Core\Routing\RouteMatchInterface $route_
   -      return '<p>' . t('Blocks are boxes of content rendered into an area, or region, of a web page. The default theme Bartik, for example, implements the regions "Sidebar first", "Sidebar second", "Featured", "Content", "Header", "Footer", etc., and a block may appear in any one of these areas. The <a href=":blocks">blocks administration page</a> provides a drag-and-drop interface for assigning a block to a region, and for controlling the order of blocks within regions.', array(':blocks' => \Drupal::url('block.admin_display'))) . '</p>';
   +      return '<p>' . t('Blocks are boxes of content rendered into an area, or region, of a web page. The default theme Bartik, for example, implements the regions "Sidebar first", "Sidebar second", "Featured", "Content", "Header", "Footer", etc., and a block may appear in any one of these areas. The <a href=":blocks">blocks administration page</a> provides a drag-and-drop interface for assigning a block to a region, and for controlling the order of blocks within regions.', [':blocks' => Url::fromRoute('block.admin_display')->toString()]) . '</p>';
   

   Unrelated change.

And then we also need to fix the similar docs on EntityTypeBundleInfoInterface::getAllBundleInfo().

Hi klausi,

I have done the changes as per your instructions but I didn't get the last sentence i.e.

And then we also need to fix the similar docs on EntityTypeBundleInfoInterface::getAllBundleInfo().

Please guide.

Thanks!!

Adding Interdiff.

Please also fix the docs on EntityTypeBundleInfoInterface::getAllBundleInfo() which returns similar data.

Hi klausi,

Added patch as per your suggestions.

Thanks!!

Adding Interdiff.

Thanks! But I think this can be improved:

1. +++ b/core/lib/Drupal/Core/Entity/EntityTypeBundleInfoInterface.php
   @@ -10,8 +10,10 @@
   +   *   An array of all existing bundle information keyed by entity type.
   +   *   Format $bundle_info[ENTITY_TYPE][BUNDLE_NAME]['label'] => [LABEL]
   +   *   Example: $bundles['node']['page']['label']
   

   I think this can be documented better.

   First of all, it's keyed (in this method) by entity type, then bundle name.

   Second, the "format" and "example" lines will not format well on api.drupal.org

   So what I suggest is something like this:

   An array of bundle information. The outer array is keyed by the entity type. The next level is keyed by the bundle name. The inner arrays area associative arrays of the bundle information, such as the label for the bundle.

   Then leave out the "format" and "bundles" lines.

2. +++ b/core/lib/Drupal/Core/Entity/EntityTypeBundleInfoInterface.php
   @@ -21,8 +23,11 @@ public function getAllBundleInfo();
   +   *   If the entity type does not have bundles then BUNDLE_TYPE is the entity
   +   *   type.
   +   *   Format $bundle_info[BUNDLE_NAME]['label'] => [LABEL]
   +   *   Example: $bundles['comment']['label']
   

   See above. Do something similar here to describe the format.

Hi jhodgdon,

I have done changes as you have said.

Please review the patch.

Thanks!!

Better, thanks! I think it still can be improved though:

1. +++ b/core/lib/Drupal/Core/Entity/EntityTypeBundleInfoInterface.php
   @@ -10,8 +10,12 @@
   +   *  An array of bundle information.
   +   *  The outer array is keyed by the entity type.
   +   *  The next level is keyed by the bundle name.
   +   *  The inner arrays area are associative arrays of the bundle information,
   +   *  such as the label for the bundle.
   

   This all needs to be wrapped into one paragraph, with close to 80 characters (without going over) in each line.

2. +++ b/core/lib/Drupal/Core/Entity/EntityTypeBundleInfoInterface.php
   @@ -21,8 +25,13 @@ public function getAllBundleInfo();
   +   *  An array of bundle information where the outer array is keyed by bundle
   

   This paragraph also needs wrapping, see above.

3. +++ b/core/lib/Drupal/Core/Entity/EntityTypeBundleInfoInterface.php
   @@ -21,8 +25,13 @@ public function getAllBundleInfo();
   +   *  If the entity type does not have bundles then BUNDLE_TYPE is the entity
   +   *  type.
   

   These two lines should be put with the first sentence (that talks about the outer array), and they shouldn't use a nonsense BUNDLE_TYPE that is not defined.

   I suggest for the first sentence, it should say:

   An array of bundle information where the outer array is keyed by the bundle name, or the entity type name if the entity does not have bundles.

4. +++ b/core/modules/help/help.api.php
   @@ -48,7 +48,7 @@ function hook_help($route_name, \Drupal\Core\Routing\RouteMatchInterface $route_
   -      return '<p>' . t('Blocks are boxes of content rendered into an area, or region, of a web page. The default theme Bartik, for example, implements the regions "Sidebar first", "Sidebar second", "Featured", "Content", "Header", "Footer", etc., and a block may appear in any one of these areas. The <a href=":blocks">blocks administration page</a> provides a drag-and-drop interface for assigning a block to a region, and for controlling the order of blocks within regions.', array(':blocks' => \Drupal::url('block.admin_display'))) . '</p>';
   +      return '<p>' . t('Blocks are boxes of content rendered into an area, or region, of a web page. The default theme Bartik, for example, implements the regions "Sidebar first", "Sidebar second", "Featured", "Content", "Header", "Footer", etc., and a block may appear in any one of these areas. The <a href=":blocks">blocks administration page</a> provides a drag-and-drop interface for assigning a block to a region, and for controlling the order of blocks within regions.', array (':blocks' => Url::fromRoute('block.admin_display'))) . '</p>';
   

   This change has nothing to do with this issue. Remove from patch.

An example says more than a thousand words, so I would suggest to put one in. We do that elsewhere, for example https://api.drupal.org/api/drupal/core!modules!views!src!Plugin!views!fi... with @code/@endcode tags.

I disagree in this case about putting in an example. Usually we do not have examples for simple nested array returns. Views is a big outlier in its API documentation...

updated patch as per suggestions in #21.

Thanks! But this is still not quite right...

1. +++ b/core/lib/Drupal/Core/Entity/EntityTypeBundleInfoInterface.php
   @@ -11,7 +11,10 @@
       * @return array
   -   *   An array of all bundle information.
   +   *  An array of bundle information where the outer array is keyed by entity
   +   *  type. The next level is keyed by the bundle name. The inner arrays are ¶
   +   *  associative arrays of the bundle information, such as the label for
   +   *  the bundle.
   

   Under @return, the documentation lines should be indented by two spaces.

2. +++ b/core/lib/Drupal/Core/Entity/EntityTypeBundleInfoInterface.php
   @@ -11,7 +11,10 @@
   +   *  type. The next level is keyed by the bundle name. The inner arrays are ¶
   

   This line should not end in a space.

3. +++ b/core/lib/Drupal/Core/Entity/EntityTypeBundleInfoInterface.php
   @@ -22,7 +25,8 @@ public function getAllBundleInfo();
       * @return array
   -   *   Returns the bundle information for the specified entity type.
   +   *  An array of bundle information where the outer array is keyed by the ¶
   +   *  bundle name, or the entity type name if the entity does not have bundles.
   

   Similar problems with spaces here (indent, end-of-line spaces).

   Also this no longer says what the inner arrays are.

I have updated the patch.

Thanks! I looked at the code, and I think this is accurate. It is also clear and well-formatted now.

The usual Migrate unrelated test failure.

Committed d13f93f and pushed to 8.1.x and 8.2.x. Thanks!