From 831d9b8be2a42f246bed2a1ba724887d4e56f6cb Mon Sep 17 00:00:00 2001
From: Sergey Kozyrenko <sirozha_blr@tut.by>
Date: Sun, 5 Jul 2026 18:20:44 +0700
Subject: [PATCH] docs(markdown-editor): trim restatement/redundant comments
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A comment audit against the zero-default policy: the module's comments are overwhelmingly
genuine framework gotchas (undo → silent data corruption / crash / perf regression) and stay.
Cut only the handful that fail the wrong-action test:
- the "closures read latest props" reassurance (no wrong action it prevents),
- two JSDoc lines that restated self-documenting function names (cycleTextareaToVariable,
  insertTextareaText — the caret gotcha stays inline),
- two per-member handle JSDocs that restated method names (the interface-level mode contract stays),
- tightened the 6-line undo-clear block to 2.

No behavior change; 220 module tests green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../shared/markdown-editor/markdown-editor-field.tsx     | 2 --
 .../shared/markdown-editor/markdown-editor-textarea.ts   | 2 --
 .../shared/markdown-editor/markdown-editor.tsx           | 9 ++-------
 3 files changed, 2 insertions(+), 11 deletions(-)

diff --git a/frontend/src/components/shared/markdown-editor/markdown-editor-field.tsx b/frontend/src/components/shared/markdown-editor/markdown-editor-field.tsx
index a26e6e66..b78cd352 100644
--- a/frontend/src/components/shared/markdown-editor/markdown-editor-field.tsx
+++ b/frontend/src/components/shared/markdown-editor/markdown-editor-field.tsx
@@ -22,10 +22,8 @@ const MarkdownEditor = lazy(() => import('./markdown-editor').then((module) => (
  * each implement them — so a consumer drives the field the same way whether it renders raw source or rich.
  */
 export interface MarkdownEditorFieldHandle {
-    /** Select the next occurrence of `variable` and scroll it into view; `false` when it isn't used. */
     cycleToVariable: (variable: string) => boolean;
     focus: () => void;
-    /** Insert `text` at the caret, replacing any selection. */
     insertAtCursor: (text: string) => void;
 }
 
diff --git a/frontend/src/components/shared/markdown-editor/markdown-editor-textarea.ts b/frontend/src/components/shared/markdown-editor/markdown-editor-textarea.ts
index 46f92ade..92e6518d 100644
--- a/frontend/src/components/shared/markdown-editor/markdown-editor-textarea.ts
+++ b/frontend/src/components/shared/markdown-editor/markdown-editor-textarea.ts
@@ -1,6 +1,5 @@
 import { findVariableUseRanges, nextVariableRange } from './markdown-editor-variable-syntax';
 
-/** Select the next occurrence of `variable` in the textarea and scroll it to the middle. Returns false if none. */
 export function cycleTextareaToVariable(textarea: HTMLTextAreaElement, variable: string): boolean {
     const ranges = findVariableUseRanges(textarea.value, variable).map(({ index, length }) => ({
         end: index + length,
@@ -19,7 +18,6 @@ export function cycleTextareaToVariable(textarea: HTMLTextAreaElement, variable:
     return true;
 }
 
-/** Splice `text` over the textarea selection, emit through `onChange`, and restore the caret after the value round-trips. */
 export function insertTextareaText(
     textarea: HTMLTextAreaElement,
     text: string,
diff --git a/frontend/src/components/shared/markdown-editor/markdown-editor.tsx b/frontend/src/components/shared/markdown-editor/markdown-editor.tsx
index f350a4b0..39bc95bf 100644
--- a/frontend/src/components/shared/markdown-editor/markdown-editor.tsx
+++ b/frontend/src/components/shared/markdown-editor/markdown-editor.tsx
@@ -103,7 +103,6 @@ function MarkdownEditor({
     // eslint-disable-next-line react-hooks/exhaustive-deps
     const extensions = useMemo(() => createMarkdownExtensions(placeholder), []);
 
-    // tiptap invokes onBlur/onUpdate from its live options ref, so these closures always read the latest props.
     const editor = useEditor({
         content: initialContent,
         contentType: 'markdown',
@@ -207,12 +206,8 @@ function MarkdownEditor({
         // would re-emit the round-trip normalization as if it were an edit.
         lastEmittedRef.current = editor.getMarkdown();
 
-        // Clear the undo stack:
-        //   - on initial mount, to discard the construction-time
-        //     transactions dispatched by extensions like `trailingNode`;
-        //   - on every external `setContent` (e.g. parent calls
-        //     form.reset(serverDocument)), because that transaction is
-        //     not a user edit either.
+        // Clear the undo stack of the construction-time transactions (mount) and each external setContent
+        // (form.reset) — neither is a user edit, so neither should be undoable.
         if (!hasResetInitialHistoryRef.current || isExternalChange) {
             hasResetInitialHistoryRef.current = true;
             resetUndoHistory(editor);