The IDE you know, rebuilt in Rust. IntelliJ IDEA–style keymap, tool windows and search-everywhere in a fast native app: editor, code insight, debugger, Git, terminal, database and HTTP clients for 60+ languages.
TypeScript code-editorcross-platformdapdatabase-clientdebuggerdesktop-appdeveloper-toolsgithttp-clientideintellijlsprusttauriterminal
feat(editor): highlight tags inside doc comments (#2200)
lleviathefd82beb309e0
diff --git a/docs/plugins/themes.md b/docs/plugins/themes.mdindex e6813bb2c..dcdf17523 100644--- a/docs/plugins/themes.md+++ b/docs/plugins/themes.md@@ -221,6 +221,7 @@ The full table is `UI_KEYS` in [`src/features/plugins/intellijTheme.ts`](../../s| `--vcs-*`, `--gutter-*` | colour `FILESTATUS_*`, `MODIFIED_LINES_COLOR`, `ADDED_LINES_COLOR`, `DELETED_LINES_COLOR` || `--syn-keyword`, `--syn-string`, `--syn-number` | `DEFAULT_KEYWORD`, `DEFAULT_STRING`, `DEFAULT_NUMBER` || `--syn-comment` (+ `--syn-comment-style`), `--syn-doc-comment` | `DEFAULT_LINE_COMMENT` (+ `FONT_TYPE`), `DEFAULT_DOC_COMMENT` |+| `--syn-doc-comment-tag`, `--syn-doc-comment-tag-value`, `--syn-doc-markup` (+ `-bg`) | `DEFAULT_DOC_COMMENT_TAG`, `DEFAULT_DOC_COMMENT_TAG_VALUE`, `DEFAULT_DOC_MARKUP` || `--syn-function`, `--syn-function-call` | `DEFAULT_FUNCTION_DECLARATION`, `DEFAULT_FUNCTION_CALL` || `--syn-type`, `--syn-constant`, `--syn-property` | `DEFAULT_CLASS_NAME`, `DEFAULT_CONSTANT`, `DEFAULT_INSTANCE_FIELD` || `--syn-variable`, `--syn-param`, `--syn-builtin` | `DEFAULT_LOCAL_VARIABLE`, `DEFAULT_PARAMETER`, `DEFAULT_PREDEFINED_SYMBOL` |@@ -328,7 +329,7 @@ a token.<!-- BEGIN GENERATED TOKEN REFERENCE: pnpm gen:theme-docs -->-247 themeable tokens: 125 in the UI theme file, 122 in the editor colour scheme file.+252 themeable tokens: 125 in the UI theme file, 127 in the editor colour scheme file.### Surfaces (UI theme)@@ -428,6 +429,11 @@ a token.| `--syn-comment` | `#7a7e85` | `#8c8c8c` || `--syn-comment-style` | `normal` | `italic` || `--syn-doc-comment` | `#5f826b` | `#8c8c8c` |+| `--syn-doc-comment-tag` | `#67a37c` | `#8c8c8c` |+| `--syn-doc-comment-tag-effect` | `none` | `underline #999999` |+| `--syn-doc-comment-tag-value` | `#abadb3` | `#3d3d3d` |+| `--syn-doc-markup` | `#68a67e` | `#8c8c8c` |+| `--syn-doc-markup-bg` | `transparent` | `#e2ffe2` || `--syn-docstring` | `#5f826b` | `#067d17` || `--syn-annotation` | `#b3ae60` | `#9e880d` || `--syn-decorator` | `#b3ae60` | `#9e880d` |diff --git a/plugins/official/harbor-night/themes/harbor-night.scheme.json b/plugins/official/harbor-night/themes/harbor-night.scheme.jsonindex 7f339c640..75363ac90 100644--- a/plugins/official/harbor-night/themes/harbor-night.scheme.json+++ b/plugins/official/harbor-night/themes/harbor-night.scheme.json@@ -12,6 +12,11 @@"--syn-comment": "#6b7a8f","--syn-comment-style": "normal","--syn-doc-comment": "#74889c",+ "--syn-doc-comment-tag": "#93abc4",+ "--syn-doc-comment-tag-effect": "none",+ "--syn-doc-comment-tag-value": "#b4c0ce",+ "--syn-doc-markup": "#8aa3b8",+ "--syn-doc-markup-bg": "transparent","--syn-docstring": "#8fb071","--syn-annotation": "#d7a0e0","--syn-decorator": "#d7a0e0",diff --git a/scripts/theme/theme.test.ts b/scripts/theme/theme.test.tsindex b70c6d80b..d40856e92 100644--- a/scripts/theme/theme.test.ts+++ b/scripts/theme/theme.test.ts@@ -184,6 +184,21 @@ describe("IntelliJ theme import", () => {expect(s.tokens["--syn-constant"]).toBeUndefined();});+ it("maps doc comment tags, tag values and markup", () => {+ const fg = (c: string) => `<value><option name="FOREGROUND" value="${c}"/></value>`;+ const s = convertIcls(`<scheme name="Docs" parent_scheme="Darcula"><attributes>+ <option name="DEFAULT_DOC_COMMENT_TAG">${fg("67a37c")}</option>+ <option name="DEFAULT_DOC_COMMENT_TAG_VALUE">${fg("abadb3")}</option>+ <option name="DEFAULT_DOC_MARKUP"><value><option name="FOREGROUND" value="68a67e"/><option name="BACKGROUND" value="e2ffe2"/></value></option>+ </attributes></scheme>`);+ expect(s.tokens).toMatchObject({+ "--syn-doc-comment-tag": "#67a37c",+ "--syn-doc-comment-tag-value": "#abadb3",+ "--syn-doc-markup": "#68a67e",+ "--syn-doc-markup-bg": "#e2ffe2",+ });+ });+it("produces an installable package", () => {const light = stripJsonComments(themeJson.replace('"dark": true,', ""));const c = convertIntellijTheme(light, icls.replace("Darcula", "Default"), "sea");diff --git a/src/editor/core/cm/docCommentTags.test.ts b/src/editor/core/cm/docCommentTags.test.tsnew file mode 100644index 000000000..5ec5be7fd--- /dev/null+++ b/src/editor/core/cm/docCommentTags.test.ts@@ -0,0 +1,302 @@+import { afterEach, describe, expect, it } from "vitest";+import { Compartment, EditorState, Prec } from "@codemirror/state";+import { Decoration, EditorView } from "@codemirror/view";+import { codeFolding, foldEffect, HighlightStyle, highlightingFor, syntaxHighlighting } from "@codemirror/language";+import { completedSyntaxState } from "@/test/syntax";+import { docCommentMarkup, docCommentTag, docCommentTagValue, openideaHighlightStyle } from "./highlight";+import { findLanguageDescription, loadSupport } from "./languages";+import { docCommentTagRanges, docCommentTags } from "./docCommentTags";++const views: EditorView[] = [];+afterEach(() => views.splice(0).forEach((v) => v.destroy()));++async function state(language: string, path: string, doc: string) {+ const support = await loadSupport(findLanguageDescription(language, path)!);+ return completedSyntaxState(EditorState.create({ doc, extensions: [support!] }));+}++function ranges(s: EditorState, language: string, from = 0) {+ return docCommentTagRanges(s, language, from, s.doc.length).map((r) => [s.sliceDoc(r.from, r.to), r.kind]);+}++describe("doc comment tags", () => {+ it("marks JavaDoc block and inline tags, @param values and HTML markup", async () => {+ const s = await state(+ "Java",+ "/p/A.java",+ [+ "/**",+ " * Sums {@link Math#addExact} values, mail [email protected].",+ " * <p>Second @param paragraph, List<String> stays text.</p>",+ " * @param <T> the type",+ " * @param left the left",+ " * @return the sum",+ " * @throws ArithmeticException on overflow",+ " */",+ "/* @param plain */",+ "// @param line",+ 'class A { String s = "/** @param x */"; /**/ }',+ "/** @deprecated use {@link B} */",+ ].join("\n"),+ );+ expect(ranges(s, "Java")).toEqual([+ ["@link", "tag"],+ ["<p>", "markup"],+ ["</p>", "markup"],+ ["@param", "tag"],+ ["<T>", "value"],+ ["@param", "tag"],+ ["left", "value"],+ ["@return", "tag"],+ ["@throws", "tag"],+ ["@deprecated", "tag"],+ ["@link", "tag"],+ ]);+ });++ it("marks KDoc tags, their subjects and [links], also when the comment starts above the range", async () => {+ const doc = [+ "/**",+ " * Adds [a] to b, see [Math.max] or [the docs](https://example.com).",+ " * @param a the a",+ " * @throws IllegalStateException never",+ " * @return the sum, {@link Foo} is not KDoc",+ " */",+ "fun f(a: Int) = a // @param x",+ "/* @param plain */",+ ].join("\n");+ const s = await state("Kotlin", "/p/a.kt", doc);+ expect(ranges(s, "Kotlin")).toEqual([+ ["[a]", "value"],+ ["[Math.max]", "value"],+ ["@param", "tag"],+ ["a", "value"],+ ["@throws", "tag"],+ ["IllegalStateException", "value"],+ ["@return", "tag"],+ ]);+ // The stream parser retains the doc-comment flag when the opener is above the range.+ expect(ranges(s, "Kotlin", doc.indexOf(" * @throws"))).toEqual([+ ["@throws", "tag"],+ ["IllegalStateException", "value"],+ ["@return", "tag"],+ ]);+ });++ it("marks JSDoc tags in JavaScript, TypeScript, JSX and TSX", async () => {+ const doc = [+ "/**",+ " * Formats {@link Date} values for [email protected].",+ " * @param {string} name the name",+ " * @returns {string}",+ " */",+ "/* @param plain */",+ "const s = '/** @param x */';",+ ].join("\n");+ for (const [language, path] of [+ ["JavaScript", "/p/a.js"],+ ["TypeScript", "/p/a.ts"],+ ["JSX", "/p/a.jsx"],+ ["TSX", "/p/a.tsx"],+ ] as const) {+ const s = await state(language, path, doc);+ expect(ranges(s, language), language).toEqual([+ ["@link", "tag"],+ ["@param", "tag"],+ ["@returns", "tag"],+ ]);+ }+ });++ it("marks PHPDoc tags and the variable of @param and @var", async () => {+ const s = await state(+ "PHP",+ "/p/a.php",+ [+ "<?php",+ "/**",+ " * Finds a user, {@inheritDoc}",+ " * @param int|string $id the id",+ " * @param array<int, string> ...$rest",+ " * @var Foo&Bar $x",+ " * @return ?User",+ " */",+ "function find($id) {} # @param $y",+ "/* @param int $z */",+ ].join("\n"),+ );+ expect(ranges(s, "PHP")).toEqual([+ ["@inheritDoc", "tag"],+ ["@param", "tag"],+ ["$id", "value"],+ ["@param", "tag"],+ ["$rest", "value"],+ ["@var", "tag"],+ ["$x", "value"],+ ["@return", "tag"],+ ]);+ });++ it.each(["Java", "Kotlin", "TypeScript", "PHP"])("rejects non-doc lookalikes in %s", async (language) => {+ const path = { Java: "A.java", Kotlin: "a.kt", TypeScript: "a.ts", PHP: "a.php" }[language]!;+ const s = await state(+ language,+ path,+ [+ language === "PHP" ? "<?php" : "",+ "@Override class A {}",+ "// @Override {@link X}",+ "/* @Override {@link X} */",+ "/* plain",+ " * @param falsePositive",+ " */",+ 'const s = "/** @param string */";',+ "/**/",+ "/** [email protected]",+ " * @return unfinished",+ ].join("\n"),+ );+ // Java and PHP do not expose unterminated block comments as comment syntax nodes.+ expect(ranges(s, language)).toEqual(language === "Java" || language === "PHP" ? [] : [["@return", "tag"]]);+ });++ it.each(["Java", "Kotlin"])("keeps tags deep inside a long %s doc comment", async (language) => {+ const doc = ["/**", ...Array.from({ length: 19997 }, () => " * @param item description"), " */", ""].join("\n");+ const s = await state(language, language === "Java" ? "A.java" : "a.kt", doc);+ expect(+ docCommentTagRanges(s, language, s.doc.line(19000).from, s.doc.line(19001).to).filter((r) => r.kind === "tag"),+ ).toHaveLength(2);+ });++ it("keeps Kotlin nested comments in their outer comment's dialect", async () => {+ const doc = "/* plain\n/** @param hidden */\n * @return hidden\n */\n/** docs\n/* nested */\n * @return shown\n */";+ const s = await state("Kotlin", "a.kt", doc);+ expect(ranges(s, "Kotlin")).toEqual([["@return", "tag"]]);+ });++ it("rebuilds decorations when the highlighter is reconfigured", async () => {+ const support = await loadSupport(findLanguageDescription("Java", "A.java")!);+ const theme = new Compartment();+ const view = new EditorView({+ parent: document.body,+ state: completedSyntaxState(+ EditorState.create({+ doc: "/** @return result */",+ extensions: [support!, theme.of(syntaxHighlighting(openideaHighlightStyle))],+ }),+ ),+ });+ views.push(view);+ const replacement = HighlightStyle.define([{ tag: docCommentTag, color: "red" }]);+ view.dispatch({ effects: theme.reconfigure(syntaxHighlighting(replacement)) });+ const cls = highlightingFor(view.state, [docCommentTag])!;+ expect(view.contentDOM.querySelector(`.${cls}`)?.textContent).toBe("@return");+ view.dispatch({ changes: { from: 2, to: 3, insert: "" } });+ expect(view.contentDOM.querySelector(`.${cls}`)).toBeNull();+ });++ it("removes decorations when switching to an unsupported language", async () => {+ const language = new Compartment();+ const support = await loadSupport(findLanguageDescription("Java", "A.java")!);+ const view = new EditorView({+ parent: document.body,+ state: completedSyntaxState(+ EditorState.create({+ doc: "/** @return result */",+ extensions: [language.of(support!), syntaxHighlighting(openideaHighlightStyle)],+ }),+ ),+ });+ views.push(view);+ const cls = highlightingFor(view.state, [docCommentTag])!;+ expect(view.contentDOM.querySelector(`.${cls}`)?.textContent).toBe("@return");+ view.dispatch({ effects: language.reconfigure([]) });+ expect(view.contentDOM.querySelector(`.${cls}`)).toBeNull();+ });++ it("keeps tag marks inside backend syntax and semantic comment marks", async () => {+ const support = await loadSupport(findLanguageDescription("Java", "A.java")!);+ const doc = "/** @return result */";+ const view = new EditorView({+ parent: document.body,+ state: completedSyntaxState(+ EditorState.create({+ doc,+ extensions: [+ support!,+ syntaxHighlighting(openideaHighlightStyle),+ Prec.high(+ EditorView.decorations.of(+ Decoration.set(Decoration.mark({ class: "backend-comment" }).range(0, doc.length)),+ ),+ ),+ Prec.highest(+ EditorView.decorations.of(+ Decoration.set(Decoration.mark({ class: "cm-sem-comment" }).range(0, doc.length)),+ ),+ ),+ ],+ }),+ ),+ });+ views.push(view);+ const cls = highlightingFor(view.state, [docCommentTag])!;+ const tag = view.contentDOM.querySelector(`.${cls}`)!;+ expect(tag.textContent).toBe("@return");+ expect(tag.closest(".backend-comment")).not.toBeNull();+ expect(tag.closest(".cm-sem-comment")).not.toBeNull();+ expect(tag.children.length).toBe(0);+ });++ it("gives other languages nothing", async () => {+ const s = await state("Rust", "/p/a.rs", "/** @param x */\nfn f() {}");+ expect(ranges(s, "Rust")).toEqual([]);+ for (const language of ["Rust", "PluginLanguage", "constructor", "toString"]) {+ expect(ranges(s, language)).toEqual([]);+ expect(docCommentTags(language)).toEqual([]);+ }+ });++ it("styles the tags with the highlight style's classes, inside the comment's own", async () => {+ const support = await loadSupport(findLanguageDescription("Java", "/p/A.java")!);+ const doc = "/**\n * See <b>this</b>.\n * @param id the id\n */\nclass A {}";+ const highlight = syntaxHighlighting(openideaHighlightStyle);+ // The language support brings the tags; whichever comes first, they nest inside the comment's marks.+ for (const extensions of [+ [support!, highlight],+ [highlight, support!],+ ]) {+ const view = new EditorView({+ parent: document.body,+ state: completedSyntaxState(EditorState.create({ doc, extensions })),+ });+ views.push(view);+ for (const [text, tag] of [+ ["@param", docCommentTag],+ ["id", docCommentTagValue],+ ["<b>", docCommentMarkup],+ ] as const) {+ const cls = highlightingFor(view.state, [tag])!;+ const span = view.contentDOM.querySelector(`.${cls}`);+ expect(span?.textContent).toBe(text);+ expect(span?.children.length).toBe(0);+ }+ }+ });++ it("keeps the tags of a line that a fold splits into two visible ranges", async () => {+ const support = await loadSupport(findLanguageDescription("Java", "/p/A.java")!);+ const doc = "/** See {@link A} and some text long enough to fold away, then {@link B}. */\nclass A {}";+ const view = new EditorView({+ parent: document.body,+ state: completedSyntaxState(+ EditorState.create({ doc, extensions: [support!, syntaxHighlighting(openideaHighlightStyle), codeFolding()] }),+ ),+ });+ views.push(view);+ view.dispatch({ effects: foldEffect.of({ from: doc.indexOf("some"), to: doc.indexOf(", then") }) });+ expect(view.visibleRanges.length).toBe(2);+ const cls = highlightingFor(view.state, [docCommentTag])!;+ expect([...view.contentDOM.querySelectorAll(`.${cls}`)].map((e) => e.textContent)).toEqual(["@link", "@link"]);+ });+});diff --git a/src/editor/core/cm/docCommentTags.ts b/src/editor/core/cm/docCommentTags.tsnew file mode 100644index 000000000..0b1744ee0--- /dev/null+++ b/src/editor/core/cm/docCommentTags.ts@@ -0,0 +1,188 @@+/**+ * Doc comment tags, as IntelliJ colours them inside `/** … *\/`: a block tag at the start of a+ * line and an inline `{@tag`, the value some tags take (a `@param` name, a KDoc subject or+ * `[link]`, a PHPDoc `$variable`) and HTML markup. Only comment nodes in the visible ranges are+ * scanned; the colours come from the highlight style (`--syn-doc-comment-tag*`, `--syn-doc-markup`).+ */+import { highlightingFor, syntaxTree } from "@codemirror/language";+import { Prec, RangeSetBuilder, type EditorState, type Extension } from "@codemirror/state";+import { Decoration, ViewPlugin, type DecorationSet, type EditorView, type ViewUpdate } from "@codemirror/view";+import { docCommentMarkup, docCommentTag, docCommentTagValue } from "./highlight";++export type DocCommentTagKind = "tag" | "value" | "markup";++export interface DocCommentTagRange {+ from: number;+ to: number;+ kind: DocCommentTagKind;+}++interface Dialect {+ /** Inline tags: `{@link …}`. */+ inline: boolean;+ /** HTML tags in the text. */+ markup: boolean;+ /** KDoc `[links]` in the text. */+ links?: boolean;+ /** The value of a block tag as `[from, to)` in `rest`, the line after the tag. */+ value?: (tag: string, rest: string) => [number, number] | null;+}++/** The value of `tags`: the last group of `value`, which ends the match. */+function valueOf(tags: RegExp, value: RegExp): Dialect["value"] {+ return (tag, rest) => {+ if (!tags.test(tag)) return null;+ const m = value.exec(rest);+ return m ? [m.index + m[0].length - m[1]!.length, m.index + m[0].length] : null;+ };+}++const JAVADOC: Dialect = { inline: true, markup: true, value: valueOf(/^@param$/, /^\s+(<\w+>|[\w$]+)/) };+const JSDOC: Dialect = { inline: true, markup: true };+// KDoc links the subject of these tags; a `[name]` anywhere in the text is a link too.+const KDOC: Dialect = {+ inline: false,+ markup: false,+ links: true,+ value: valueOf(/^@(?:param|property|throws|exception|see|sample)$/, /^\s+(\[[^\]\n]+\]|[\w.]+)/),+};+const PHPDOC: Dialect = {+ inline: true,+ markup: true,+ value: valueOf(/^@(?:[a-z]+-)?(?:param|var|property(?:-read|-write)?)$/, /^.*?(?:\s|&|\.\.\.)(\$[A-Za-z_]\w*)/),+};++/** By CodeMirror language name (`LanguageDescription.name`). */+const DIALECTS: Record<string, Dialect> = {+ Java: JAVADOC,+ Kotlin: KDOC,+ JavaScript: JSDOC,+ TypeScript: JSDOC,+ JSX: JSDOC,+ TSX: JSDOC,+ "Angular TypeScript": JSDOC,+ PHP: PHPDOC,+};++const COMMENT = /comment/i;+/** Indentation and the leading `*` of a comment line. */+const LEAD = /^\s*\**\s*/;+const BLOCK_TAG = /^@[A-Za-z][\w\\-]*/;+const INLINE_TAG = /\{@[A-Za-z][\w-]*/g;+const LINK = /\[[^[\]\n]+\](?![([])/g;+// Known HTML elements only, so generics such as `List<String>` stay text.+const MARKUP =+ /<\/?(?:a|abbr|b|big|blockquote|br|caption|cite|code|dd|del|details|div|dl|dt|em|h[1-6]|hr|i|img|ins|kbd|li|ol|p|pre|q|s|samp|section|small|span|strong|sub|summary|sup|table|tbody|td|th|thead|tr|tt|u|ul|var)\b[^<>]*>/gi;+/** `/**` opens a doc comment; `/**\/` is an empty block comment. */+const opensDoc = (head: string) => head.startsWith("/**") && !head.startsWith("/**/");++function scanComment(+ state: EditorState,+ dialect: Dialect,+ comment: { from: number; to: number },+ range: { from: number; to: number },+ out: DocCommentTagRange[],+) {+ const end = Math.min(comment.to, range.to);+ for (let pos = Math.max(comment.from, range.from); pos <= end;) {+ const line = state.doc.lineAt(pos);+ const from = Math.max(line.from, comment.from);+ let text = state.sliceDoc(from, Math.min(line.to, comment.to));+ if (text.endsWith("*/")) text = text.slice(0, -2);+ const skip = from === comment.from && opensDoc(text.slice(0, 4)) ? 3 : 0;+ const lead = skip + LEAD.exec(text.slice(skip))![0].length;+ const tag = BLOCK_TAG.exec(text.slice(lead));+ if (tag) {+ const at = from + lead;+ out.push({ from: at, to: at + tag[0].length, kind: "tag" });+ const value = dialect.value?.(tag[0], text.slice(lead + tag[0].length));+ if (value) out.push({ from: at + tag[0].length + value[0], to: at + tag[0].length + value[1], kind: "value" });+ }+ const rest = text.slice(skip);+ const base = from + skip;+ if (dialect.inline)+ for (const m of rest.matchAll(INLINE_TAG))+ out.push({ from: base + m.index + 1, to: base + m.index + m[0].length, kind: "tag" });+ if (dialect.links)+ for (const m of rest.matchAll(LINK))+ out.push({ from: base + m.index, to: base + m.index + m[0].length, kind: "value" });+ if (dialect.markup)+ for (const m of rest.matchAll(MARKUP))+ out.push({ from: base + m.index, to: base + m.index + m[0].length, kind: "markup" });+ pos = line.to + 1;+ }+}++/** Tag, value and markup ranges in the doc comments between `from` and `to`, sorted, without overlaps. */+export function docCommentTagRanges(+ state: EditorState,+ language: string,+ from: number,+ to: number,+): DocCommentTagRange[] {+ const dialect = Object.hasOwn(DIALECTS, language) ? DIALECTS[language] : undefined;+ if (!dialect) return [];+ const found: DocCommentTagRange[] = [];+ syntaxTree(state).iterate({+ from,+ to,+ enter: (node) => {+ if (!COMMENT.test(node.name)) return;+ const doc =+ language === "Kotlin" ? node.name === "docComment" : opensDoc(state.sliceDoc(node.from, node.from + 4));+ if (doc) scanComment(state, dialect, node, { from, to }, found);+ return false;+ },+ });+ found.sort((a, b) => a.from - b.from);+ const out: DocCommentTagRange[] = [];+ for (const r of found) if (!out.length || r.from >= out[out.length - 1]!.to) out.push(r);+ return out;+}++const TAGS = { tag: docCommentTag, value: docCommentTagValue, markup: docCommentMarkup };+const marks = new Map<string, Decoration>();++function decorations(view: EditorView, language: string): DecorationSet {+ // A fold inside one line splits it into two visible ranges that both scan that whole line.+ const found = view.visibleRanges+ .flatMap((range) => docCommentTagRanges(view.state, language, range.from, range.to))+ .sort((a, b) => a.from - b.from);+ const builder = new RangeSetBuilder<Decoration>();+ let end = -1;+ for (const r of found) {+ if (r.from < end) continue;+ const cls = highlightingFor(view.state, [TAGS[r.kind]]);+ if (!cls) continue;+ let mark = marks.get(cls);+ if (!mark) marks.set(cls, (mark = Decoration.mark({ class: cls })));+ builder.add(r.from, r.to, mark);+ end = r.to;+ }+ return builder.finish();+}++/** Doc comment tag highlighting for a CodeMirror language (by name); none where IntelliJ has none. */+export function docCommentTags(language: string): Extension {+ if (!Object.hasOwn(DIALECTS, language)) return [];+ // Above the syntax highlighters (Lezer and tree-sitter), so the marks nest inside the comment's and win.+ const plugin = ViewPlugin.fromClass(+ class {+ decorations: DecorationSet;+ constructor(view: EditorView) {+ this.decorations = decorations(view, language);+ }+ update(u: ViewUpdate) {+ if (+ u.docChanged ||+ u.viewportChanged ||+ u.transactions.some((t) => t.reconfigured) ||+ syntaxTree(u.state) !== syntaxTree(u.startState)+ )+ this.decorations = decorations(u.view, language);+ }+ },+ { decorations: (v) => v.decorations },+ );+ return Prec.highest(plugin);+}diff --git a/src/editor/core/cm/highlight.ts b/src/editor/core/cm/highlight.tsindex 78285557d..ec7b3671f 100644--- a/src/editor/core/cm/highlight.ts+++ b/src/editor/core/cm/highlight.ts@@ -9,6 +9,10 @@ import { Tag, tags as t } from "@lezer/highlight";/** Log warnings: the UI warning colour, since no syntax token reads as one in every scheme. */export const logWarning = Tag.define("logWarning");export const parameter = Tag.define(t.variableName);+/** Inside doc comments, as IntelliJ colours them: `@param` / `{@link`, a `@param` name, HTML markup. */+export const docCommentTag = Tag.define(t.docComment);+export const docCommentTagValue = Tag.define(t.docComment);+export const docCommentMarkup = Tag.define(t.docComment);function token(tag: Tag | Tag[],@@ -66,6 +70,9 @@ export const openideaHighlightStyle = HighlightStyle.define([),token([t.comment, t.lineComment, t.blockComment], "comment", { italic: "var(--syn-comment-style)" }),token(t.docComment, "doc-comment", { italic: "italic" }),+ token(docCommentTag, "doc-comment-tag", { italic: "normal", bold: "var(--fw-code, 400)" }),+ token(docCommentTagValue, "doc-comment-tag-value", { italic: "normal", bold: "var(--fw-code, 400)" }),+ token(docCommentMarkup, "doc-markup", { italic: "normal", bold: "var(--fw-code, 400)" }),token([t.meta, t.annotation, t.macroName], "decorator"),// `<!doctype>` is a sub-tag of `meta`; PyCharm leaves the XML prologue as plain text.{ tag: t.documentMeta, color: "var(--fg-editor)" },diff --git a/src/editor/core/cm/interpolation.ts b/src/editor/core/cm/interpolation.tsindex 51d0f3d84..ea894d2b1 100644--- a/src/editor/core/cm/interpolation.ts+++ b/src/editor/core/cm/interpolation.ts@@ -10,7 +10,15 @@ type Literal = {multiline: boolean;braces: number;};-type Frame<S> = { code: S; literal?: Literal; depth: number; name?: boolean; close?: string };+type Frame<S> = {+ code: S;+ literal?: Literal;+ depth: number;+ name?: boolean;+ close?: string;+ doc?: boolean;+ commentDepth?: number;+};type State<S> = { frames: Frame<S>[]; indentUnit: number };/** Preserve the stock code tokenizer while suspending strings around embedded code. */@@ -129,7 +137,18 @@ export function interpolationParser<S>(base: StreamParser<S>, dialect: Interpolaif (text[0] === "}") frame.depth--;}stream.pos = from;- return base.token(stream, frame.code);+ const result = base.token(stream, frame.code);+ if (dialect === "Kotlin" && result === "comment" && (frame.commentDepth || text.startsWith("/*"))) {+ // Keep the doc flag in the incremental parser state, including through nested comments.+ const doc = frame.commentDepth ? frame.doc : text.startsWith("/**") && !text.startsWith("/**/");+ let depth = frame.commentDepth ?? 0;+ for (const delimiter of stream.string.slice(from, stream.pos).matchAll(/\/\*|\*\//g))+ depth += delimiter[0] === "/*" ? 1 : -1;+ frame.commentDepth = depth;+ frame.doc = depth > 0 && doc;+ return doc ? "docComment" : result;+ }+ return result;},};}diff --git a/src/editor/core/cm/languages.ts b/src/editor/core/cm/languages.tsindex 51f06c177..4c8d78ed9 100644--- a/src/editor/core/cm/languages.ts+++ b/src/editor/core/cm/languages.ts@@ -20,6 +20,7 @@ import { languages as languageData } from "@codemirror/language-data";import type { DocBackend, LanguageInfo } from "../backend";import { _languageMode } from "@/editor/api";import { JS_TAGS } from "./jsTags";+import { docCommentTags } from "./docCommentTags";let infos: Map<string, LanguageInfo> | null = null;let infosPromise: Promise<Map<string, LanguageInfo>> | null = null;@@ -303,6 +304,7 @@ function patchSupport(desc: LanguageDescription, support: LanguageSupport): Lang: support.language;const patched = new LanguageSupport(language, [support.support,+ docCommentTags(desc.name),EditorView.editorAttributes.of({ "data-language": desc.name }),]);// `loadedSupport` reads `desc.support` synchronously; keep it on the patched instance.diff --git a/src/features/plugins/intellijTheme.ts b/src/features/plugins/intellijTheme.tsindex b24bb3f3f..5e19770ee 100644--- a/src/features/plugins/intellijTheme.ts+++ b/src/features/plugins/intellijTheme.ts@@ -135,6 +135,12 @@ export const ICLS_ATTRIBUTES: Record<string, Array<[Part, string]>> = {DEFAULT_NUMBER: [["FOREGROUND", "--syn-number"]],DEFAULT_LINE_COMMENT: [["FOREGROUND", "--syn-comment"]],DEFAULT_DOC_COMMENT: [["FOREGROUND", "--syn-doc-comment"]],+ DEFAULT_DOC_COMMENT_TAG: [["FOREGROUND", "--syn-doc-comment-tag"]],+ DEFAULT_DOC_COMMENT_TAG_VALUE: [["FOREGROUND", "--syn-doc-comment-tag-value"]],+ DEFAULT_DOC_MARKUP: [+ ["FOREGROUND", "--syn-doc-markup"],+ ["BACKGROUND", "--syn-doc-markup-bg"],+ ],DEFAULT_FUNCTION_DECLARATION: [["FOREGROUND", "--syn-function"]],DEFAULT_FUNCTION_CALL: [["FOREGROUND", "--syn-function-call"]],DEFAULT_CLASS_NAME: [["FOREGROUND", "--syn-type"]],diff --git a/src/features/settings/__tests__/colorScheme.test.tsx b/src/features/settings/__tests__/colorScheme.test.tsxindex 2a961f287..4fd6b211e 100644--- a/src/features/settings/__tests__/colorScheme.test.tsx+++ b/src/features/settings/__tests__/colorScheme.test.tsx@@ -121,6 +121,42 @@ describe("scheme actions", () => {});});+describe("doc comment scheme attributes", () => {+ it.each([+ ["en", "Doc comment", "Tag", "Tag value", "Markup"],+ ["zh", "文档注释", "标签", "标签值", "标记"],+ ])("groups, previews, edits and resets doc attributes in %s", async (locale, group, tag, valueName, markup) => {+ await act(async () => {+ await setLocale(locale);+ });+ try {+ act(() => stage("editor.colorScheme", "global", "editor.colorScheme", "dark"));+ schemePage("editor.colorScheme.language-defaults");+ const preview = screen.getByLabelText(locale === "en" ? "Color scheme preview" : "配色方案预览");+ for (const [sample, label, id] of [+ ["@param", tag, "docCommentTag"],+ ["id", valueName, "docCommentTagValue"],+ ["<b>", markup, "docCommentMarkup"],+ ]) {+ act(() => fireEvent.click(within(preview).getByText(sample!)));+ expect(screen.getAllByRole("treeitem", { name: group })).toHaveLength(1);+ expect(screen.getByRole("treeitem", { name: label, selected: true })).toBeInTheDocument();+ act(() => fireEvent.click(screen.getByRole("checkbox", { name: locale === "en" ? "Bold" : "粗体" })));+ act(() => fireEvent.click(screen.getByRole("checkbox", { name: locale === "en" ? "Italic" : "斜体" })));+ expect(value("colorOverrides")).toMatchObject({ dark: { [id!]: { bold: true, italic: true } } });+ }+ act(() =>+ fireEvent.click(screen.getByRole("button", { name: locale === "en" ? "Restore Defaults" : "恢复默认值" })),+ );+ expect(value("colorOverrides")).toEqual({});+ } finally {+ await act(async () => {+ await setLocale("en");+ });+ }+ });+});+describe("Go scheme attributes", () => {it("translates the attribute tree and preview selection in Chinese", async () => {await act(async () => {diff --git a/src/features/settings/pages/editor/colorScheme.tsx b/src/features/settings/pages/editor/colorScheme.tsxindex 9f3359009..cd74d36f9 100644--- a/src/features/settings/pages/editor/colorScheme.tsx+++ b/src/features/settings/pages/editor/colorScheme.tsx@@ -249,9 +249,12 @@ const SAMPLES: Record<string, CodeSample> = {],[[" /**", "docComment"],- [" doc comment ", "docComment"],- ["@param", "docComment"],- [" id", "docComment"],+ [" <b>", "docCommentMarkup"],+ ["doc comment", "docComment"],+ ["</b> ", "docCommentMarkup"],+ ["@param", "docCommentTag"],+ [" ", "docComment"],+ ["id", "docCommentTagValue"],[" */", "docComment"],],[diff --git a/src/platform/colorScheme.test.ts b/src/platform/colorScheme.test.tsindex a3082dc06..762bf1812 100644--- a/src/platform/colorScheme.test.ts+++ b/src/platform/colorScheme.test.ts@@ -29,6 +29,12 @@ describe("color schemes", () => {expect(dark.get("--syn-python-bytes")).toBe("#a5c261");});+ it.each(["light", "dark"] as const)("inherits new doc tokens for older %s custom schemes", (parent) => {+ const customs = { "custom-old": { name: "Old", parent, attributes: {} } };+ for (const id of ["docCommentTag", "docCommentTagValue", "docCommentMarkup"])+ expect(resolvedAttribute("custom-old", id, customs)).toEqual(resolvedAttribute(parent, id));+ });+it("gives PHP variables and function calls their own colours, as PhpStorm (#1532)", () => {expect(schemeTokens("dark").get("--syn-php-variable")).toBe("#c77dbb");expect(schemeTokens("dark").get("--syn-php-function-call")).toBe("#56a8f5");diff --git a/src/platform/colorScheme.ts b/src/platform/colorScheme.tsindex 8a7ef88c9..a1a48914d 100644--- a/src/platform/colorScheme.ts+++ b/src/platform/colorScheme.ts@@ -137,7 +137,10 @@ const BASE_ATTRIBUTES: readonly AttributeDef[] = [syn("string", "String › String text", [LD], "string"),syn("escape", "String › Valid escape sequence", [LD], "escape"),syn("lineComment", "Comments › Line comment", [LD], "comment"),- syn("docComment", "Comments › Doc comment", [LD], "doc-comment", { defaultItalic: true }),+ syn("docComment", "Comments › Doc comment › Text", [LD], "doc-comment", { defaultItalic: true }),+ syn("docCommentTag", "Comments › Doc comment › Tag", [LD], "doc-comment-tag"),+ syn("docCommentTagValue", "Comments › Doc comment › Tag value", [LD], "doc-comment-tag-value"),+ { ...syn("docCommentMarkup", "Comments › Doc comment › Markup", [LD], "doc-markup"), bg: "--syn-doc-markup-bg" },syn("metadata", "Metadata", [LD], "decorator"),syn("operator", "Braces and Operators", [LD], "punct"),syn("markupTag", "Markup › Tag", [LD], "tag"),@@ -208,6 +211,7 @@ export const ATTRIBUTES: readonly AttributeDef[] = [const SCHEME_VARS = new Set<string>([...ATTRIBUTES.flatMap((a) => [a.fg, a.bg, a.effect].filter((v): v is string => !!v)),"--syn-comment-style",+ "--syn-doc-comment-tag-effect","--editor-error-decoration","--editor-warning-decoration","--editor-warning-background",diff --git a/src/platform/icls.test.ts b/src/platform/icls.test.tsindex 705242c13..7d4f9ca59 100644--- a/src/platform/icls.test.ts+++ b/src/platform/icls.test.ts@@ -25,6 +25,43 @@ describe(".icls schemes", () => {expect(scheme.attributes["php.string"]).toBeUndefined();});+ it("maps doc comment tags, tag values and markup per language", () => {+ const fg = (c: string) => `<value><option name="FOREGROUND" value="${c}"/></value>`;+ const { scheme } = parseIcls(`<scheme name="Docs" parent_scheme="Darcula"><attributes>+ <option name="DEFAULT_DOC_COMMENT_TAG">${fg("67a37c")}</option>+ <option name="DEFAULT_DOC_COMMENT_TAG_VALUE">${fg("abadb3")}</option>+ <option name="DEFAULT_DOC_MARKUP"><value><option name="BACKGROUND" value="e2ffe2"/></value></option>+ <option name="JAVA_DOC_TAG">${fg("111111")}</option>+ <option name="KDOC_LINK">${fg("222222")}</option>+ <option name="PHP_DOC_TAG">${fg("333333")}</option>+ <option name="PHP_DOC_VAR">${fg("444444")}</option>+ <option name="PHP_ATTRIBUTE">${fg("555555")}</option>+ </attributes></scheme>`);+ expect(scheme.attributes.docCommentTag?.foreground).toBe("#67a37c");+ expect(scheme.attributes.docCommentTagValue?.foreground).toBe("#abadb3");+ expect(scheme.attributes.docCommentMarkup?.background).toBe("#e2ffe2");+ expect(scheme.attributes["java.docCommentTag"]?.foreground).toBe("#111111");+ expect(scheme.attributes["kotlin.docCommentTagValue"]?.foreground).toBe("#222222");+ expect(scheme.attributes["php.docCommentTag"]?.foreground).toBe("#333333");+ expect(scheme.attributes["php.docCommentTagValue"]?.foreground).toBe("#444444");+ // PhpStorm's PHP 8 attributes, which PHP_DOC_TAG used to stand in for.+ expect(scheme.attributes["php.metadata"]?.foreground).toBe("#555555");+ const css = schemeCss("custom-docs", undefined, null, { "custom-docs": scheme });+ expect(css).toContain("--syn-doc-comment-tag: #67a37c !important");+ expect(css).toContain("--syn-doc-markup-bg: #e2ffe2 !important");+ const imported = parseIcls(exportIcls("custom-docs", { "custom-docs": scheme })).scheme;+ for (const id of [+ "docCommentTag",+ "docCommentTagValue",+ "docCommentMarkup",+ "java.docCommentTag",+ "kotlin.docCommentTagValue",+ "php.docCommentTag",+ "php.docCommentTagValue",+ ])+ expect(imported.attributes[id]).toMatchObject(scheme.attributes[id]!);+ });+it("preserves PHP colours and regular styles separately from Java and language defaults", () => {const { scheme } = parseIcls(fixture("monokai-php"));expect(scheme.parent).toBe("dark");diff --git a/src/platform/icls.ts b/src/platform/icls.tsindex f4f155c5f..0e5abb23f 100644--- a/src/platform/icls.ts+++ b/src/platform/icls.ts@@ -27,6 +27,9 @@ const ATTRIBUTE_NAMES: Record<string, string> = {DEFAULT_LINE_COMMENT: "lineComment",DEFAULT_BLOCK_COMMENT: "lineComment",DEFAULT_DOC_COMMENT: "docComment",+ DEFAULT_DOC_COMMENT_TAG: "docCommentTag",+ DEFAULT_DOC_COMMENT_TAG_VALUE: "docCommentTagValue",+ DEFAULT_DOC_MARKUP: "docCommentMarkup",DEFAULT_METADATA: "metadata",DEFAULT_OPERATION_SIGN: "operator",DEFAULT_BRACES: "operator",@@ -107,6 +110,11 @@ Object.assign(ATTRIBUTE_NAMES, {KOTLIN_EXTENSION_FUNCTION_CALL: "kotlin.functionCall",KOTLIN_NAMED_ARGUMENT: "kotlin.parameter",KOTLIN_OBJECT: "kotlin.className",+ JAVA_DOC_TAG: "java.docCommentTag",+ DOC_COMMENT_TAG_VALUE: "java.docCommentTagValue",+ JAVA_DOC_MARKUP: "java.docCommentMarkup",+ KDOC_TAG_NAME: "kotlin.docCommentTag",+ KDOC_LINK: "kotlin.docCommentTagValue",CLASS_NAME_ATTRIBUTES: "className",PHP_KEYWORD: "php.keyword",PHP_VAR: "php.identifier",@@ -124,7 +132,10 @@ Object.assign(ATTRIBUTE_NAMES, {PHP_ESCAPE_SEQUENCE: "php.escape",PHP_COMMENT: "php.lineComment",PHP_DOC_COMMENT_ID: "php.docComment",- PHP_DOC_TAG: "php.metadata",+ PHP_DOC_TAG: "php.docCommentTag",+ PHP_DOC_VAR: "php.docCommentTagValue",+ PHP_MARKUP_ID: "php.docCommentMarkup",+ PHP_ATTRIBUTE: "php.metadata",PHP_OPERATION_SIGN: "php.operator",PHP_BRACKETS: "php.brackets",PHP_COMMA: "php.separator",diff --git a/src/platform/locales/text/en.json b/src/platform/locales/text/en.jsonindex e16d65813..cf5934c3a 100644--- a/src/platform/locales/text/en.json+++ b/src/platform/locales/text/en.json@@ -36,10 +36,12 @@"Comments": "Comments","Line comment": "Line comment","Doc comment": "Doc comment",+ "Text": "Text","Metadata": "Metadata","Braces and Operators": "Braces and Operators","Markup": "Markup","Tag": "Tag",+ "Tag value": "Tag value","Attribute": "Attribute","Contents differ only in line separators": "Contents differ only in line separators","Cannot remove a worktree containing the open project.": "Cannot remove a worktree containing the open project.",diff --git a/src/platform/locales/text/zh.json b/src/platform/locales/text/zh.jsonindex 21455ff0a..6eeaaea3f 100644--- a/src/platform/locales/text/zh.json+++ b/src/platform/locales/text/zh.json@@ -2489,6 +2489,7 @@"Tabs and Indents": "制表符和缩进","Tag": "标签","Tag name:": "标签名称:",+ "Tag value": "标签值","Tags to push": "要推送的标签","Target changelist": "目标更改列表","Target directory": "目标目录",diff --git a/src/styles/tokens.css b/src/styles/tokens.cssindex 7f103e261..6214044e3 100644--- a/src/styles/tokens.css+++ b/src/styles/tokens.css@@ -116,6 +116,11 @@ html {--syn-comment: #7a7e85;--syn-comment-style: normal;--syn-doc-comment: #5f826b;+ --syn-doc-comment-tag: #67a37c;+ --syn-doc-comment-tag-effect: none;+ --syn-doc-comment-tag-value: #abadb3;+ --syn-doc-markup: #68a67e;+ --syn-doc-markup-bg: transparent;--syn-docstring: #5f826b;--syn-annotation: #b3ae60;--syn-decorator: #b3ae60;@@ -521,6 +526,11 @@ html {--syn-comment: #8c8c8c;--syn-comment-style: italic;--syn-doc-comment: #8c8c8c;+ --syn-doc-comment-tag: #8c8c8c;+ --syn-doc-comment-tag-effect: underline #999999;+ --syn-doc-comment-tag-value: #3d3d3d;+ --syn-doc-markup: #8c8c8c;+ --syn-doc-markup-bg: #e2ffe2;--syn-docstring: #067d17;--syn-annotation: #9e880d;--syn-decorator: #9e880d;@@ -799,6 +809,11 @@ html {--syn-function-call: #e3e4e8;--syn-comment: #a5a9b0;--syn-doc-comment: #8fb89c;+ --syn-doc-comment-tag: #8fcca3;+ --syn-doc-comment-tag-effect: none;+ --syn-doc-comment-tag-value: #d2d4d9;+ --syn-doc-markup: #90c9a3;+ --syn-doc-markup-bg: transparent;--syn-docstring: #8fb89c;--syn-annotation: #d6d17a;--syn-decorator: #d6d17a;@@ -1166,6 +1181,11 @@ html {--syn-function-call: var(--palette-blue);--syn-comment: var(--palette-comment);--syn-doc-comment: var(--palette-comment);+ --syn-doc-comment-tag: var(--palette-keyword);+ --syn-doc-comment-tag-effect: none;+ --syn-doc-comment-tag-value: var(--palette-variable);+ --syn-doc-markup: var(--syn-doc-comment);+ --syn-doc-markup-bg: transparent;--syn-docstring: var(--palette-green);--syn-annotation: var(--palette-orange);--syn-decorator: var(--palette-orange);