diff --git a/src/JsonApiResource/LinkCollection.php b/src/JsonApiResource/LinkCollection.php
index 40aa85d..3727935 100644
--- a/src/JsonApiResource/LinkCollection.php
+++ b/src/JsonApiResource/LinkCollection.php
@@ -14,7 +14,7 @@ class LinkCollection implements \IteratorAggregate {
   /**
    * The links in the collection, keyed by unique strings.
    *
-   * @var array|\Drupal\jsonapi\JsonApiResource\WebLink[]
+   * @var array
    */
   protected $links;
 
@@ -48,16 +48,14 @@ class LinkCollection implements \IteratorAggregate {
    * Gets a new LinkCollection with the given link inserted.
    *
    * @param string $key
-   *   A key for the link. If the key already exists, the given link will either
-   *   be merged with the existing link or both keys will have a unique string
-   *   appended to them. The link will only be merged with an existing link if
-   *   they share the same base key.
+   *   A key for the link. If the key already exists and the link shares an href
+   *   with an existing link with that key, those links will be merged together.
    * @param \Drupal\jsonapi\JsonApiResource\WebLink $new_link
    *   The link to insert.
    *
    * @return static
-   *   A new LinkCollection with the given link inserted or merged the current
-   *   set of links.
+   *   A new LinkCollection with the given link inserted or merged with the
+   *   current set of links.
    */
   public function withLink($key, WebLink $new_link) {
     assert(static::validKey($key));
@@ -75,7 +73,7 @@ class LinkCollection implements \IteratorAggregate {
   }
 
   /**
-   * Filters a link collection using the provided callback.
+   * Filters a LinkCollection using the provided callback.
    *
    * @param callable $f
    *   The filter callback. The callback has the signature below.
diff --git a/src/JsonApiResource/WebLink.php b/src/JsonApiResource/WebLink.php
index 30a46e4..9ab874b 100644
--- a/src/JsonApiResource/WebLink.php
+++ b/src/JsonApiResource/WebLink.php
@@ -9,9 +9,9 @@ use Drupal\Core\Cache\CacheableMetadata;
 use Drupal\Core\Url;
 
 /**
- * Represents an RFC5988 based web link.
+ * Represents an RFC8288 based web link.
  *
- * @see https://tools.ietf.org/html/rfc5988
+ * @see https://tools.ietf.org/html/rfc8288
  *
  * @internal
  */
diff --git a/src/Normalizer/LinkCollectionNormalizer.php b/src/Normalizer/LinkCollectionNormalizer.php
index cf0b296..2278bf7 100644
--- a/src/Normalizer/LinkCollectionNormalizer.php
+++ b/src/Normalizer/LinkCollectionNormalizer.php
@@ -11,6 +11,17 @@ use Drupal\jsonapi\Normalizer\Value\NormalizedValue;
 /**
  * Normalizes a LinkCollection object.
  *
+ * The JSON API specification has the concept of a "links collection". A links
+ * collection is a JSON object where each member of the object is a
+ * "link object". Unfortunately, this means that it is not possible to have more
+ * than one link for a given key.
+ *
+ * When normalizing more than one link in a LinkCollection with the same key, a
+ * unique and random string is appended to the link's key after a colon (:) to
+ * differentiate the links.
+ *
+ * This may change with later version of the JSON API specification.
+ *
  * @internal
  */
 class LinkCollectionNormalizer extends NormalizerBase {