diff --git a/core/lib/Drupal/Core/Entity/Annotation/EntityType.php b/core/lib/Drupal/Core/Entity/Annotation/EntityType.php
index b8e4061..b412089 100644
--- a/core/lib/Drupal/Core/Entity/Annotation/EntityType.php
+++ b/core/lib/Drupal/Core/Entity/Annotation/EntityType.php
@@ -253,11 +253,19 @@ class EntityType extends Plugin {
   public $menu_path_wildcard;
 
   /**
-   * Link templates using the URI template syntax.
-   *
-   * Links are an array of standard link relations to the URI template that
-   * should be used for them. Where possible, link relationships should use
-   * established IANA relationships rather than custom relationships.
+   * Link path patterns for viewing and administering the entity.
+   *
+   * Path patterns are defined in an associative array where the key is the
+   * type of path, and the value is the path pattern. For example:
+   * - canonical: /entity/{entityType}/{id}
+   * - edit-form: /node/{id}/edit
+   * - version-history: /node/{id}/revisions
+   *
+   * The path types are more formerly known as entity link relationships, and
+   * they should be given standard names from the Internet Assigned Numbers
+   * Authority (IANA). A complete listing of IANA URI Template Relationships is
+   * available online here:
+   * @link http://www.iana.org/assignments/link-relations/link-relations.xml @endlink
    *
    * Every entity type should, at minimum, define "canonical", which is the
    * pattern for URIs to that entity. Even if the entity will have no HTML page
@@ -265,7 +273,9 @@ class EntityType extends Plugin {
    * compatible with web services. Entities that will be user-editable via an
    * HTML page must also define an "edit-form" relationship.
    *
-   * By default, the following placeholders are supported:
+   * Use placeholders wrapped in braces, for example {entityType}, to include a
+   * specific property of the entity in the template. By default, the following
+   * placeholders are supported:
    * - entityType: The machine name of the entity type.
    * - bundle: The bundle machine name of the entity.
    * - id: The unique ID of the entity.
@@ -278,9 +288,9 @@ class EntityType extends Plugin {
    * Specific entity types may also expand upon this list by overriding the
    * uriPlaceholderReplacements() method.
    *
-   * @link http://www.iana.org/assignments/link-relations/link-relations.xml @endlink
-   * @link http://tools.ietf.org/html/rfc6570 @endlink
-   *
+   * @see http://www.iana.org/assignments/link-relations/link-relations.xml
+   * @see http://tools.ietf.org/html/rfc6570
+   * @see http://tools.ietf.org/html/rfc6596
    * @var array
    */
   public $links = array(