diff --git a/typings/xterm.d.ts b/typings/xterm.d.ts
index 15a03327..0b3b3977 100644
--- a/typings/xterm.d.ts
+++ b/typings/xterm.d.ts
@@ -1159,7 +1159,18 @@ declare module '@xterm/xterm' {
     deregisterCharacterJoiner(joinerId: number): void;
 
     /**
-     * Adds a marker to the normal buffer and returns it.
+     * Adds a marker to the normal buffer and returns it.  
+     * NOTE: If you are synchronously writing data line-by-line (as in, doing 
+     * multiple `term.writeln()`before the terminal re-rendering), the cursorY 
+     * position will not be updated until after all pending terminal writes, 
+     * which will result in the markers offset being calculated from the
+     * position cursorY was when your batch of writes started.  
+     * Dealing with this issue by setting `cursorYOffset` to be index of this 
+     * line in your batch will fail if you have any line wraps prior to it.  
+     * Instead, consider registering a marker inside a write callback, eg.:
+     * ```ts
+     * term.writeln(data, () => term.registerMarker(...))
+     * ```
      * @param cursorYOffset The y position offset of the marker from the cursor.
      * @returns The new marker or undefined.
      */