From 98cc2b4bebdf8dcf6cbb422b0b1d1a08aecce58e Mon Sep 17 00:00:00 2001
From: overlookmotel <557937+overlookmotel@users.noreply.github.com>
Date: Sat, 10 Oct 2026 12:19:11 +0000
Subject: [PATCH] docs(linter/plugins): improve documentation for
 `firstCommentAtOrAfter` (#27538)

Comments-only-update. Follow-on after #27393.

That PR introduced a function `firstCommentAtOrAfter`. Improve the JSDoc comment for it.
---
 apps/oxlint/src-js/plugins/comments_methods.ts | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/apps/oxlint/src-js/plugins/comments_methods.ts b/apps/oxlint/src-js/plugins/comments_methods.ts
index bf566d5ecc..6ac367ca89 100644
--- a/apps/oxlint/src-js/plugins/comments_methods.ts
+++ b/apps/oxlint/src-js/plugins/comments_methods.ts
@@ -229,7 +229,15 @@ export function commentsExistBetween(
   );
 }
 
-/** Find the first comment whose `start` is at or after `offset`. */
+/**
+ * Find the first comment whose `start` is at or after `offset`.
+ *
+ * Searched range starts at `startIndex` and ends at `length`.
+ * Returns `length` if all comments have `start` < `offset`.
+ *
+ * Note: Source text is limited to 1 GiB max, so number of comments cannot exceed 2^30.
+ * This makes it safe to use `>> 1` for division by 2 below (which is faster than `>>> 1`).
+ */
 function firstCommentAtOrAfter(
   int32: Int32Array,
   offset: number,