Skip to content

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.

feat(editor): highlight tags inside doc comments (#2200)

lleviathefd82beb309e0
diff --git a/docs/plugins/themes.md b/docs/plugins/themes.md
index 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.json
index 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.ts
index 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.ts
new file mode 100644
index 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 */";',
+ "/**/",
+ " * @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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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: Interpola
if (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.ts
index 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.ts
index 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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.json
index 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.json
index 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.css
index 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);