diff --git a/core/lib/Drupal/Core/Entity/entity.api.php b/core/lib/Drupal/Core/Entity/entity.api.php
index 8c75a5e..5a850e8 100644
--- a/core/lib/Drupal/Core/Entity/entity.api.php
+++ b/core/lib/Drupal/Core/Entity/entity.api.php
@@ -301,10 +301,10 @@
  *     Configuration Translation module, without the need of a controller class.
  *   - access: If your configuration entity has complex permissions, you might
  *     need an access control handling, implementing
- *     \Drupal\Core\Entity\EntityAccessControlHandlerInterface, but most entities
- *     can just use the 'admin_permission' annotation instead. Note that if you
- *     are creating your own access control handler, you should override the
- *     checkAccess() and checkCreateAccess() methods, not access().
+ *     \Drupal\Core\Entity\EntityAccessControlHandlerInterface, but most
+ *     entities can just use the 'admin_permission' annotation instead. Note
+ *     that if you are creating your own access control handler, you should
+ *     override the checkAccess() and checkCreateAccess() methods, not access().
  *   - storage: A class implementing
  *     \Drupal\Core\Entity\EntityStorageInterface. If not specified, content
  *     entities will use \Drupal\Core\Entity\Sql\SqlContentEntityStorage, and
@@ -321,17 +321,12 @@
  *   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:
- *   "entity.$entity_type_id.$link_template_type". See @ref sec_routes below for
- *   some routing notes. Typical link types are:
+ *   also need to take care of entity routing; see @ref sec_routes below for
+ *   some notes.
+ * - You will need to define URLs for entity operations. These go into the
+ *   'links' annotation, with the link type as the key, and the URL template
+ *   for the link the value. You'll also need to take care of entity routing;
+ *   see @ref sec_routes below for notes on that. Typical link types are:
  *   - canonical: Default link, either to view (if entities are viewed on their
  *     own pages) or edit the entity.
  *   - delete-form: Confirmation form to delete the entity.
@@ -358,10 +353,13 @@
  *   \Drupal\Core\Entity\EntityType.
  *
  * @section sec_routes Entity routes
- * Entity routes, like other routes, are defined in *.routing.yml files; see
- * the @link menu Menu and routing @endlink topic for more information. Entities
- * may alternatively use an auto route provider class. See an example in the end
- * of this section. Here is a typical entry, for the block configure form:
+ * There are two ways to define entity routes. First, you can define them
+ * like other routes in *.routing.yml files; see the
+ * @link menu Menu and routing @endlink topic for more information. If you do
+ * this, your route names need to have the format entity.ENTITY_TYPE.LINK_TYPE,
+ * where ENTITY_TYPE is your entity type's machine name, and LINK_TYPE is one of
+ * the link types in your links annotation (with hyphens changed to
+ * underscores). Here is a typical entry, for the block configure form:
  * @code
  * entity.block.edit_form:
  *   path: '/admin/structure/block/manage/{block}'
@@ -371,12 +369,13 @@
  *   requirements:
  *     _entity_access: 'block.update'
  * @endcode
+ *
  * Some notes:
  * - path: The {block} in the path is a placeholder, which (for an entity) must
- *   always take the form of {machine_name_of_entity_type}. In the URL, the
- *   placeholder value will be the ID of an entity item. When the route is used,
- *   the entity system will load the corresponding entity item and pass it in as
- *   an object to the controller for the route.
+ *   always take the form of {ENTITY_TYPE}. In the URL, the placeholder value
+ *   will be the ID of an entity item. When the route is used, the entity system
+ *   will load the corresponding entity item and pass it in as an object to the
+ *   controller for the route.
  * - defaults: For entity form routes, use _entity_form rather than the generic
  *   _controller or _form. The value is composed of the entity type machine name
  *   and a form controller type from the entity annotation (see @ref define
@@ -388,17 +387,25 @@
  *     "form" = {
  *       "default" = "Drupal\block\BlockForm",
  *   @endcode
- * - Instead of putting the routes for your entity in a *.routing.yml file, you
- *   can instead use a route provider class.
- *   DefaultHtmlRouteProvider provides canonical, edit-form, and delete-form.
- *   Use AdminHtmlRouteProvider to provide the same with edit-form and
- *   delete-form using the admin theme. You can also create your own class. To
- *   use a route provider, add the following to your entity annotation:
- *   @code
- *   handlers = {
- *     "route_provider" = {
- *       "html" = "Drupal\Core\Entity\Routing\DefaultHtmlRouteProvider",
- *   @endcode
+ *
+ * As an alternative to providing routes for your entity in a *.routing.yml
+ * file, you can instead use a route provider class. To do this, put the name of
+ * the route provider class you want to use into the handlers section of the
+ * entity annotation, like this:
+ * @code
+ * handlers = {
+ *   "route_provider" = {
+ *     "html" = "Drupal\Core\Entity\Routing\DefaultHtmlRouteProvider",
+ * @endcode
+ *
+ * Drupal core provides two route providers you can use:
+ * - \Drupal\Core\Entity\Routing\DefaultHtmlRouteProvider provides routes
+ *   for canonical, edit-form, and delete-form routes.
+ * - \Drupal\Core\Entity\Routing\AdminHtmlRouteProvider provides the same
+ *   routes, specifying that the edit and delete routes should use the admin
+ *   theme.
+ * You can also create your own class to provide routes; typically you would
+ * extend one of these two classes.
  *
  * @section bundle Defining a content entity bundle
  * For entity types that use bundles, such as Node (bundles are content types)