diff --git a/src/structs/Item.js b/src/structs/Item.js
index deaea0ae..061275c3 100644
--- a/src/structs/Item.js
+++ b/src/structs/Item.js
@@ -385,6 +385,7 @@ export class Item extends AbstractStruct {
       return this.parent.client
     }
     if (this.content.constructor === ContentType && /** @type {ContentType} */ (this.content).type.constructor === YWeakLink) {
+      // make sure that linked content is integrated first
       const content = /** @type {any} */ (this.content).type
       if (content._id.client !== this.id.client) {
         return content._id.client
@@ -523,8 +524,9 @@ export class Item extends AbstractStruct {
         // set as current parent value if right === null and this is parentSub
         /** @type {AbstractType<any>} */ (this.parent)._map.set(this.parentSub, this)
         if (this.left !== null) {
-          // this is the current attribute value of parent. delete right
+          // inherit links from block we're overriding
           this.linkedBy = this.left.linkedBy
+          // this is the current attribute value of parent. delete right
           this.left.delete(transaction)
         }
       }
diff --git a/src/types/YWeakLink.js b/src/types/YWeakLink.js
index 5cbf106d..2953aaff 100644
--- a/src/types/YWeakLink.js
+++ b/src/types/YWeakLink.js
@@ -77,6 +77,9 @@ export class YWeakLink extends AbstractType {
     super._integrate(y, item)
     if (item !== null) {
       transact(y, (transaction) => {
+        // link may refer to a single element in multi-element block
+        // in such case we need to cut of the linked element into a
+        // separate block
         let sourceItem = this._linkedItem !== null ? this._linkedItem : getItemCleanStart(transaction, this._id)
         if (sourceItem.constructor === Item && sourceItem.parentSub !== null) {
           // for maps, advance to most recent item