diff --git a/docs/src/demos/Experiments/Annotation/extension/AnnotationState.ts b/docs/src/demos/Experiments/Annotation/extension/AnnotationState.ts
index 45c4073a..41d5d319 100644
--- a/docs/src/demos/Experiments/Annotation/extension/AnnotationState.ts
+++ b/docs/src/demos/Experiments/Annotation/extension/AnnotationState.ts
@@ -89,7 +89,7 @@ export class AnnotationState {
   }
 
   apply(transaction: Transaction, state: EditorState) {
-    const ystate = ySyncPluginKey.getState(state)
+    // Add/Remove annotations
     const action = transaction.getMeta(AnnotationPluginKey) as AddAnnotationAction | DeleteAnnotationAction
 
     if (action && action.type) {
@@ -104,13 +104,16 @@ export class AnnotationState {
       return this
     }
 
+    // Use Y.js to update positions
+    const ystate = ySyncPluginKey.getState(state)
+
     if (ystate.isChangeOrigin) {
       this.updateDecorations(state)
 
       return this
     }
 
-    // Apply ProseMirror mapping
+    // Use ProseMirror to update positions
     this.decorations = this.decorations.map(transaction.mapping, transaction.doc)
 
     return this
diff --git a/docs/src/demos/Experiments/Annotation/extension/annotation.ts b/docs/src/demos/Experiments/Annotation/extension/annotation.ts
index 7a6c92c0..47e2905a 100644
--- a/docs/src/demos/Experiments/Annotation/extension/annotation.ts
+++ b/docs/src/demos/Experiments/Annotation/extension/annotation.ts
@@ -4,6 +4,7 @@ import { AnnotationItem } from './AnnotationItem'
 import { AnnotationPlugin, AnnotationPluginKey } from './AnnotationPlugin'
 
 function randomId() {
+  // TODO: That seems … to simple.
   return Math.floor(Math.random() * 0xffffffff)
 }
 
@@ -23,13 +24,16 @@ export interface AnnotationOptions {
   HTMLAttributes: {
     [key: string]: any
   },
+  /**
+   * An event listener which receives annotations for the current selection.
+   */
   onUpdate: (items: [any?]) => {},
   /**
    * An initialized Y.js document.
    */
   document: Y.Doc | null,
   /**
-   * Name of a Y.js fragment, can be changed to sync multiple fields with one Y.js document.
+   * Name of a Y.js map, can be changed to sync multiple fields with one Y.js document.
    */
   field: string,
   /**