Issue #2229931 by xjm, Berdir: Improve documentation related to config object...

Issue #2229931 by xjm, Berdir: Improve documentation related to config object filename component limits

core/lib/Drupal/Core/Config/Entity/ConfigEntityStorage.php

@@ -42,13 +42,15 @@ class ConfigEntityStorage extends EntityStorageBase implements ConfigEntityStora
   /**
    * Length limit of the configuration entity ID.
    *
-   * Most file systems limit a file name's length to 255 characters. In
-   * order to leave sufficient characters to construct a configuration prefix,
-   * the configuration entity ID is limited to 166 characters which
-   * leaves 83 characters for the configuration prefix. 5 characters are
-   * reserved for the file extension.
+   * Most file systems limit a file name's length to 255 characters, so
+   * ConfigBase::MAX_NAME_LENGTH restricts the full configuration object name
+   * to 250 characters (leaving 5 for the file extension). The config prefix
+   * is limited by ConfigEntityType::PREFIX_LENGTH to 83 characters, so this
+   * leaves 166 remaining characters for the configuration entity ID, with 1
+   * additional character needed for the joining dot.
    *
    * @see \Drupal\Core\Config\ConfigBase::MAX_NAME_LENGTH
+   * @see \Drupal\Core\Config\Entity\ConfigEntityType::PREFIX_LENGTH
    */
   const MAX_ID_LENGTH = 166;
 

core/lib/Drupal/Core/Config/Entity/ConfigEntityType.php

@@ -19,13 +19,32 @@ class ConfigEntityType extends EntityType {
   /**
    * Length limit of the configuration entity prefix.
    *
-   * Most file systems limit a file name's length to 255 characters. In
+   * Configuration entity names are composed of two parts:
+   * - The config prefix, which is returned by getConfigPrefix() and is
+   *   composed of:
+   *   - The provider module name (limited to 50 characters by
+   *     DRUPAL_EXTENSION_NAME_MAX_LENGTH).
+   *   - The module-specific namespace identifier, which defaults to the
+   *     configuration entity type ID. Entity type IDs are limited to 32
+   *     characters by EntityTypeInterface::ID_MAX_LENGTH.
+   * - The configuration entity ID.
+   * So, a typical configuration entity filename will look something like:
+   * provider_module_name.namespace_identifier.config_entity_id.yml
+   *
+   * Most file systems limit a file name's length to 255 characters, so
+   * ConfigBase::MAX_NAME_LENGTH restricts the full configuration object name
+   * to 250 characters (leaving 5 for the file extension). Therefore, in
    * order to leave sufficient characters to construct a configuration ID,
-   * the configuration entity prefix is limited to 83 characters which
-   * leaves 166 characters for the configuration ID. 5 characters are
-   * reserved for the file extension.
+   * the configuration entity prefix is limited to 83 characters: up to 50
+   * characters for the module name, 1 for the dot, and 32 for the namespace
+   * identifier. This also allows modules with shorter names to define longer
+   * namespace identifiers if desired.
    *
    * @see \Drupal\Core\Config\ConfigBase::MAX_NAME_LENGTH
+   * @see \Drupal\Core\Config\Entity\ConfigEntityTypeInterface::getConfigPrefix()
+   * @see DRUPAL_EXTENSION_NAME_MAX_LENGTH
+   * @see \Drupal\Core\Config\Entity\ConfigEntityStorage::MAX_ID_LENGTH
+   * @see \Drupal\Core\Entity\EntityTypeInterface::ID_MAX_LENGTH
    */
   const PREFIX_LENGTH = 83;