From 0411228be7fb996f06e9e5d26b49e625d5ef6b78 Mon Sep 17 00:00:00 2001
From: Pokey Rule <755842+pokey@users.noreply.github.com>
Date: Mon, 17 Jul 2023 14:26:02 +0100
Subject: [PATCH] Add comment explaining why we need `getRemovalHighlightRange`

---
 .../cursorless-engine/src/typings/target.types.ts   | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/packages/cursorless-engine/src/typings/target.types.ts b/packages/cursorless-engine/src/typings/target.types.ts
index 2310901037..c0a34f0606 100644
--- a/packages/cursorless-engine/src/typings/target.types.ts
+++ b/packages/cursorless-engine/src/typings/target.types.ts
@@ -136,6 +136,19 @@ export interface Target {
   /** The range of the delimiter after the content selection */
   getTrailingDelimiterTarget(): Target | undefined;
   getRemovalRange(): Range;
+
+  /**
+   * The range that should be highlighted when the target is removed. Note that
+   * we can't just use `getRemovalRange()`, because when we highlight a line for
+   * removal, we don't know which line to highlight just based on the removal
+   * range.
+   *
+   * For example, assume that the document, represented as a string, is `"\n"`.
+   * This corresponds to a document with two empty lines. If we say `"chuck
+   * line"` on either line, the removal range will be the entire document, but
+   * we want to highlight the line that they were on when they said `"chuck
+   * line"`, as that is logically the line they've deleted.
+   */
   getRemovalHighlightRange(): Range;
   withThatTarget(thatTarget: Target): Target;
   withContentRange(contentRange: Range): Target;