diff --git a/core/modules/content_translation/src/Tests/ContentTranslationContextualLinksTest.php b/core/modules/content_translation/src/Tests/ContentTranslationContextualLinksTest.php
index 36a0d20..d264e47 100644
--- a/core/modules/content_translation/src/Tests/ContentTranslationContextualLinksTest.php
+++ b/core/modules/content_translation/src/Tests/ContentTranslationContextualLinksTest.php
@@ -71,9 +71,7 @@ protected function setUp() {
     $this->bundle = $this->randomMachineName();
     $this->contentType = $this->drupalCreateContentType(array('type' => $this->bundle));
 
-    // Add a field to the content type. This will be made translatable by the
-    // test through the UI. This is important because it tests that caches are
-    // cleared as expected when doing this.
+    // Add a field to the content type. The field is not yet translatable.
     entity_create('field_storage_config', array(
       'field_name' => 'field_test_text',
       'entity_type' => 'node',
@@ -112,7 +110,8 @@ public function testContentTranslationContextualLinks() {
     $this->drupalCreateNode(array('type' => $this->bundle, 'title' => $title, 'langcode' => 'en'));
     $node = $this->drupalGetNodeByTitle($title);
 
-    // Set up the node type and field to be translatable through the UI.
+    // Use a UI form sumission to make the node type and field translatable.
+    // This tests that caches are properly invalidated.
     $this->drupalLogin($this->rootUser);
     $edit = array(
       'entity_types[node]' => TRUE,
diff --git a/core/modules/system/entity.api.php b/core/modules/system/entity.api.php
index 9d9b33e..e0cdcfc 100644
--- a/core/modules/system/entity.api.php
+++ b/core/modules/system/entity.api.php
@@ -619,12 +619,16 @@ function hook_ENTITY_TYPE_create_access(\Drupal\Core\Session\AccountInterface $a
  * Modules may implement this hook to add information to defined entity types,
  * as defined in \Drupal\Core\Entity\EntityTypeInterface.
  *
+ * To alter existing information or to add information dynamically, use
+ * hook_entity_type_alter().
+ *
  * @param \Drupal\Core\Entity\EntityTypeInterface[] $entity_types
  *   An associative array of all entity type definitions, keyed by the entity
  *   type name. Passed by reference.
  *
  * @see \Drupal\Core\Entity\Entity
  * @see \Drupal\Core\Entity\EntityTypeInterface
+ * @see hook_entity_type_alter()
  */
 function hook_entity_type_build(array &$entity_types) {
   /** @var $entity_types \Drupal\Core\Entity\EntityTypeInterface[] */
@@ -641,8 +645,11 @@ function hook_entity_type_build(array &$entity_types) {
  * \Drupal\Core\Entity\Annotation\EntityType and all the ones additionally
  * provided by modules can be altered here.
  *
- * Do not use this hook to add information to entity types, unless you are just
- * filling-in default values. Use hook_entity_type_build() instead.
+ * Do not use this hook to add information to entity types, unless:
+ * - you are just filling in default values,
+ * - you need to dynamically add information only in certain circumstances, or
+ * - your hook needs to run after hook_entity_type_build() implementations.
+ * Use hook_entity_type_build() instead in all other cases.
  *
  * @param \Drupal\Core\Entity\EntityTypeInterface[] $entity_types
  *   An associative array of all entity type definitions, keyed by the entity