diff --git a/dynamic_entity_reference.install b/dynamic_entity_reference.install
index 907208d..7990598 100644
--- a/dynamic_entity_reference.install
+++ b/dynamic_entity_reference.install
@@ -11,6 +11,23 @@ use Drupal\Core\Entity\Sql\SqlEntityStorageInterface;
 
 /**
  * Changes target_id column to string and creates target_id_int.
+ *
+ * This is an incredible mess because
+ * \Drupal\Core\Entity\Sql\SqlContentEntityStorageSchema::updateDedicatedTableSchema()
+ * throws a \Drupal\Core\Entity\Exception\FieldStorageDefinitionUpdateForbiddenException
+ * when there is a column change even if the change is doable without problem --
+ * like this update here which changes the int target_id column to string. So
+ * this routine needs to find all target_id columns and cast them manually.
+ * After that,
+ * \Drupal\Core\Entity\Sql\SqlContentEntityStorageSchema::saveFieldSchemaData(0
+ * is protected so the field storage schema need to be saved into the key-value
+ * storage. On top of this, shared tables store the field definition objects in
+ * yet another key-value storage which also needs to manually kept up-to-date.
+ *
+ * Finally
+ * \Drupal\dynamic_entity_reference\EventSubscriber\FieldStorageSubscriber::handleEntityType()
+ * is called to add the triggers.
+ *
  */
 function dynamic_entity_reference_update_8001() {
   /** @var \Drupal\Core\Entity\EntityFieldManagerInterface $entity_field_manager */
diff --git a/src/EventSubscriber/FieldStorageSubscriber.php b/src/EventSubscriber/FieldStorageSubscriber.php
index c6e43e6..823a3fa 100644
--- a/src/EventSubscriber/FieldStorageSubscriber.php
+++ b/src/EventSubscriber/FieldStorageSubscriber.php
@@ -69,6 +69,13 @@ class FieldStorageSubscriber implements EventSubscriberInterface {
    * {@inheritdoc}
    */
   public static function getSubscribedEvents() {
+    // When enabling a module implementing providing an entity type,
+    // EntityTypeEvents::CREATE fires and FieldStorageDefinitionEvents::CREATE
+    // does not. On the other hand, when adding a field
+    // to an existing entity type, EntityTypeEvents::UPDATE does not fire but
+    // FieldStorageDefinitionEvents::CREATE does. This is true for saving a
+    // FieldStorageConfig object or enabling a module implementing
+    // hook_entity_base_field_info().
     $events[FieldStorageDefinitionEvents::CREATE][] = ['onFieldStorage', 100];
     $events[EntityTypeEvents::CREATE][] = ['onEntityType', 100];
     return $events;
@@ -113,7 +120,6 @@ class FieldStorageSubscriber implements EventSubscriberInterface {
    */
   public function handleEntityType($entity_type_id, FieldStorageDefinitionInterface $field_storage_definition = NULL) {
     $storage = $this->entityTypeManager->getStorage($entity_type_id);
-    $entity_type = $this->entityTypeManager->getDefinition($entity_type_id);
     $der_fields = $this->entityFieldManager->getFieldMapByFieldType('dynamic_entity_reference');
     if ($field_storage_definition) {
       $der_fields[$entity_type_id][$field_storage_definition->getName()] = TRUE;