diff --git a/core/lib/Drupal/Core/Entity/entity.api.php b/core/lib/Drupal/Core/Entity/entity.api.php
index 251a87c..73e9723 100644
--- a/core/lib/Drupal/Core/Entity/entity.api.php
+++ b/core/lib/Drupal/Core/Entity/entity.api.php
@@ -317,19 +317,11 @@
  *   tables and their fields. These annotation properties, such as 'base_table',
  *   'data_table', 'entity_keys', etc., are documented on
  *   \Drupal\Core\Entity\EntityType.
- * - For content entities that are displayed on their own pages, the annotation
- *   will refer to a 'uri_callback' function, which takes an object of the
- *   entity interface you have defined as its parameter, and returns routing
- *   information for the entity page; see node_uri() for an example. You will
- *   also need to add a corresponding route to your module's routing.yml file;
- *   see the entity.node.canonical route in node.routing.yml for an example, and see
- *   @ref sec_routes below for some notes.
- * - Optionally, instead of defining routes, routes can be auto generated by
- *   providing a route handler. See @ref sec_routes. Otherwise, define routes
- *   and links for the various URLs associated with the entity.
- *   These go into the 'links' annotation, with the link type as the key, and
- *   the path of this link template as the value. The corresponding route
- *   requires the following route name:
+ * - Routes can be automatically generated by providing a route handler. See
+ *   @ref sec_routes. Otherwise, define routes and links for the various URLs
+ *   associated with the entity. These go into the 'links' annotation, with the
+ *   link type as the key, and the path of this link template as the value. The
+ *   corresponding route requires the following route name:
  *   "entity.$entity_type_id.$link_template_type". See @ref sec_routes below for
  *   some routing notes. Typical link types are:
  *   - canonical: Default link, either to view (if entities are viewed on their
@@ -337,6 +329,13 @@
  *   - delete-form: Confirmation form to delete the entity.
  *   - edit-form: Editing form.
  *   - Other link types specific to your entity type can also be defined.
+ * - For content entities that are displayed on their own pages, the annotation
+ *   may also refer to a 'uri_callback' function, which is used as a fallback
+ *   when a 'links' annotation entry cannot be found for a requested link type.
+ *   This function takes an object of the entity interface you have defined as
+ *   its parameter, and returns a URL object for the entity page; see
+ *   taxonomy_term_uri() for an example. This feature is deprecated and the
+ *   'links' annotation should be used in preference.
  * - If your content entity is fieldable, provide 'field_ui_base_route'
  *   annotation, giving the name of the route that the Manage Fields, Manage
  *   Display, and Manage Form Display pages from the Field UI module will be
@@ -714,7 +713,8 @@ function hook_entity_view_mode_info_alter(&$view_modes) {
  *   - uri_callback: The same as the 'uri_callback' key defined for the entity
  *     type in the EntityManager, but for the bundle only. When determining
  *     the URI of an entity, if a 'uri_callback' is defined for both the
- *     entity type and the bundle, the one for the bundle is used.
+ *     entity type and the bundle, and the one for the entity type would
+ *     normally be used, the one for the bundle is used instead.
  *   - translatable: (optional) A boolean value specifying whether this bundle
  *     has translation support enabled. Defaults to FALSE.
  *