feat(formatter): add JSDoc comment formatting support

[Dunqing]

Summary

Implements native JSDoc comment formatting in oxfmt, porting behavior from prettier-plugin-jsdoc (v1.8.0). Tracked in #19702.

Conformance

145/145 (100%) compatibility with prettier-plugin-jsdoc test suite.

• 1 fixture intentionally skipped (descriptions/032-jsx-tsx-css) — requires embedded CSS/HTML formatter callbacks not available in the standalone conformance runner
• Run with: cargo run -p oxc_prettier_conformance -- --jsdoc

Architecture

The formatting pipeline processes each JSDoc comment through these stages:

1. Parse — Extract JSDoc structure via oxc_jsdoc (description, tags with type/name/comment)
2. Normalize — Canonicalize tag aliases (@return → @returns), normalize types (Array.<T> → T[], ?Type → Type | null), normalize markdown emphasis (__bold__ → **bold**, *italic* → _italic_)
3. Sort & Group — Sort tags by upstream priority weights within @typedef/@callback groups; reorder @param tags to match function signature
4. Format — Route each tag to its specific formatter (type+name+comment, type+comment, generic, example); format descriptions via markdown AST with word wrapping; format embedded code blocks
5. Serialize — Assemble final comment with /** ... */ wrapper, * prefixes, and single-line optimization

Key modules:

• serialize.rs — Main pipeline orchestrator (JsdocFormatter struct)
• tag_formatters.rs — Tag-specific formatters (type+name+comment, type+comment, generic, example)
• normalize.rs — Type/emphasis/capitalization normalization
• mdast_serialize.rs — Markdown AST → formatted text serialization with tag_string_length offset
• wrap.rs — Word wrapping with first_line_offset, atomic JSDoc link tokens, table formatting
• embedded.rs — Embedded JS/TS/JSX/TSX code formatting in @example blocks
• line_buffer.rs — Single-allocation line accumulator

Options Support

All 11 options from prettier-plugin-jsdoc are implemented:

Option	Default	Status
jsdocCapitalizeDescription	true	✅
jsdocCommentLineStrategy	"singleLine"	✅
jsdocSeparateTagGroups	false	✅
jsdocSeparateReturnsFromParam	false	✅
jsdocBracketSpacing	false	✅
jsdocDescriptionWithDot	false	✅
jsdocAddDefaultToDescription	true	✅
jsdocPreferCodeFences	false	✅
jsdocLineWrappingStyle	"greedy"	✅ (greedy + balance)
jsdocDescriptionTag	false	✅
jsdocKeepUnParseAbleExampleIndent	false	✅

Not yet ported (no conformance fixtures): jsdocVerticalAlignment, tsdoc mode — can be added when needed.

Features

• Description formatting: Capitalize first letter, normalize markdown emphasis, wrap text to print width
• Markdown AST processing: Parse descriptions via mdast for heading normalization, list formatting, reference links, code blocks, blockquotes, tables
• Tag description wrapping: Matches upstream's tagStringLength architecture — full description passes through markdown AST with first-line offset, no custom word-fitting
• Tag normalization: 17 tag synonyms, sort by upstream priority weights within groups
• Type formatting: Normalize JSDoc types, format via the formatter's TS parser (simulating upstream's formatType()), handle rest params, bracket spacing
• @example formatting: Format embedded JS/TS/JSX/TSX code; delegate CSS/HTML/GraphQL/Markdown to external formatter callbacks
• @import handling: Parse, merge by module path, sort (third-party before relative), format consolidated imports
• @param reordering: Reorder tags to match function signature parameter order
• Default value handling: Extract [name=value] defaults with "Default is `value`" suffix

Upstream Fidelity

Verified against prettier-plugin-jsdoc v1.8.0 source:

• Identical: Tag synonyms (17), sort priorities (46 tags), grouping logic (TAGS_GROUP_HEAD, TAGS_GROUP_CONDITION), type normalization pipeline, rest param handling, JSDoc link protection, emphasis normalization, capitalization rules
• Architecture aligned: Tag description wrapping uses tag_string_length / first_line_offset (equivalent to upstream's !...? prefix trick), balance mode effective width calculation, greedy fallback

Performance

• Single LineBuffer allocation per comment (one contiguous String, not Vec<String>)
• Cow<'_, str> throughout normalization — borrows when unchanged, allocates only when modified
• Fast-path skip of mdast parsing for plain-text descriptions (needs_mdast_parsing() heuristic)
• Fast-path skip of TS formatter for simple types (needs_formatter_pass() check)
• SmallVec<[usize; 4]> for import tag indices (stack allocation for common case)

Test plan

• cargo test -p oxc_formatter — 203 tests pass
• cargo run -p oxc_prettier_conformance -- --jsdoc — 145/145 (100%)
• cargo clippy -p oxc_formatter --all-targets — clean
• cargo fmt -- --check — clean
• Benchmark: cargo run -p oxc_formatter --example formatter -- --jsdoc <file>

🤖 Generated with Claude Code

[codspeed-hq]

Merging this PR will degrade performance by 8.54%

❌ 2 regressed benchmarks
✅ 51 untouched benchmarks
⏩ 3 skipped benchmarks¹

⚠️ Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
❌	Simulation	formatter[next.ts]	2.7 ms	2.8 ms	-4.29%
❌	Simulation	formatter[handle-comments.js]	3.5 ms	3.8 ms	-8.54%

---

_{Comparing feat/jsdoc-comment-formatting (870ffbf) with main (542a04a)}

Footnotes

1. 3 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[Copilot]

Pull request overview

This PR implements native JSDoc comment formatting support in oxc_formatter, porting behavior from prettier-plugin-jsdoc. It adds a configurable JsdocOptions struct, string-based JSDoc comment reformatting (tag normalization, description capitalization, type normalization, word wrapping, etc.), and a dedicated JSDoc conformance test runner. The PR also integrates JSDoc support into the oxfmt app configuration.

Changes:

• Adds JsdocOptions to FormatOptions and implements JSDoc comment formatting in the Comment::fmt() hook in trivia.rs
• Introduces a new JsdocTestRunner for running prettier-plugin-jsdoc conformance tests, with a large fixture set (115 input/output pairs)
• Extends oxfmtrc.rs with a jsdoc: Option<bool> config field and wires it through to the formatter options

Reviewed changes

Copilot reviewed 277 out of 280 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
crates/oxc_formatter/src/options.rs	Adds JsdocOptions struct and jsdoc field on FormatOptions
crates/oxc_formatter/src/formatter/trivia.rs	Integrates JSDoc formatting in Comment::fmt()
crates/oxc_formatter/src/formatter/jsdoc/	New submodules: normalize, wrap, serialize, mdast_serialize
crates/oxc_jsdoc/src/parser/jsdoc_parts.rs	Adds parsed_preserving_whitespace() and raw() methods
tasks/prettier_conformance/src/jsdoc.rs	New JsdocTestRunner with fixture discovery and option loading
tasks/prettier_conformance/jsdoc/fixtures/	Large set of input/output fixture pairs for conformance testing
tasks/prettier_conformance/jsdoc/snapshots/jsdoc.snap.md	Generated snapshot showing 115/115 compatibility
apps/oxfmt/src/core/oxfmtrc.rs	Adds jsdoc: Option<bool> config field
apps/oxfmt/test/api/jsdoc.test.ts	API test for CSS/HTML fenced block formatting
IMPLEMENTATION_PLAN.md	Internal planning document committed to the repo
crates/oxc_formatter/build.rs	Fixes has_test_files() to avoid unused import warnings
crates/oxc_formatter/Cargo.toml	Adds oxc_jsdoc and markdown dependencies

Files not reviewed (1)

• tasks/prettier_conformance/jsdoc/scripts/package-lock.json: Language not supported

[Boshen]

Is this good slop?

[Dunqing]

Is this good slop?

I think it is! I steered Claude code and Codex to the right direction; now all JSDoc tests have passed, and mostly the code is aligned with upstream. But now I just looked at less code, so I assume there are sill room to improve, and also I plan to let them move some logic to oxc_jsdoc when possible so that it could benefit all that crate dependent.

[Dunqing]

JSDoc Benchmark Regression Analysis

Instrumented the JSDoc formatting path with per-comment timing (release build) to understand the 8.46% regression on handle-comments.js and 4.11% on next.ts.

Benchmark Files — JSDoc Comment Density

File	Lines	JSDoc Count	Multi-line	With Tags	JSDoc % of file	Regression
handle-comments.js	1092	10	9	9	4.2%	-8.46%
next.ts	619	6	1	2	2.1%	-4.11%
App.tsx	11181	27	19	4	1.0%	untouched
types.ts	2371	1	1	1	0.1%	untouched
core.js	427	0	0	0	0.0%	untouched

Per-Comment Timing

handle-comments.js (total JSDoc time: ~900µs out of 3.5ms baseline → ~25% overhead)

#	Lines	Chars	Result	Time	Note
1	L29	52	SKIP	~260µs	First-call init overhead (1-line @import)
2	L31-41	326	SKIP	~55µs	11-line @typedef with 9 tags
3-7	L47-142	55-64	SKIP	~2µs each	Simple @param/@returns
8	L953-968	290	FORMAT	~590µs	16-line comment with description + code block — the big one
9	L989-1002	141	FORMAT	~6µs	14-line code example
10	L1069-1072	51	SKIP	~2µs	Simple 4-line

next.ts (total JSDoc time: ~420µs out of 2.7ms baseline → ~15% overhead)

#	Lines	Chars	Result	Time	Note
1	L56	42	SKIP	~110µs	First-call init overhead
2	L58	39	SKIP	~93µs	Second-call warmup
3-4	L60,125	37-46	SKIP	~1-2µs	Single-line
5	L160-163	133	FORMAT	~215µs	4-line @internal with description
6	L365	81	SKIP	~2µs	Single-line

Root Causes

1. First-call overhead (~250-300µs): The first JSDoc comment processed per file pays an initialization cost — likely lazy statics, regex compilation, or allocator warmup in the markdown/JSDoc parsing pipeline. This shows up even for SKIP'd (unchanged) comments.

2. Markdown parsing for descriptions (~200-600µs per comment): Comments containing descriptions with paragraphs or code blocks go through format_description_mdast which does full markdown AST parsing + word wrapping. Comment Diagnostics Handling and Printing #8 in handle-comments.js alone costs ~590µs — roughly 17% of the 3.5ms baseline.

3. Even SKIP'd comments pay a cost: format_jsdoc_comment must parse the JSDoc, sort tags, and build formatted output before comparing against the original to decide nothing changed — then returning None. The 11-line @typedef (L31-41, 326 chars, 9 tags) takes ~55µs even though it's ultimately unchanged.

Optimization Opportunities

1. Cache/amortize first-call init: The ~250µs first-call penalty per file could be reduced by pre-initializing regex/statics.
2. Fast-path for tags-only JSDoc: Comments with only @param/@returns tags and no description (most of handle-comments.js) could skip markdown parsing entirely.
3. Early bail-out for unchanged comments: A quick structural fingerprint before doing full formatting could avoid the full parse→format→compare cycle for comments that won't change.

[Dunqing]

• perf(formatter): reduce clone overhead in JSDoc formatting #20136
• feat(formatter): add JSDoc comment formatting support #19828 👈 (View in Graphite)
• main

---

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

• 0-merge - adds this PR to the back of the merge queue
• hotfix - for urgent hot fixes, skip the queue and merge this PR next

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

[Dunqing]

Real-World Testing Report

Tested oxfmt's JSDoc formatting against Prettier + prettier-plugin-jsdoc v1.8.0 on 5 real-world repositories to validate correctness after the latest fixes.

Correctness Results

Repository	Stars	JSDoc Tags	JSDoc Diffs	Non-JSDoc Diffs
evoluhq/evolu	3.7k	~11	0	0 files
wxt-dev/wxt	9.3k	~325	0	8 files
TypeStrong/typedoc	7.7k	~478	0	254 files
chartjs/Chart.js	65k	~495	0	66 files
sveltejs/svelte	82k	~5,733	0	3,161 files

Zero JSDoc formatting differences across ~7,000+ JSDoc tags in 5 repositories.

Non-JSDoc diffs are expected general code formatting differences (line wrapping heuristics, quote style, trailing commas) unrelated to this PR.

Performance Overhead

Benchmarked with hyperfine (multi-threaded, --check mode where available):

Repository	Files	JSDoc Comments	Without JSDoc	With JSDoc	Overhead
evolu	248	~11	16.5 ms	22.9 ms	+6.4 ms (38%)
wxt	325	~325	15.8 ms	19.5 ms	+3.7 ms (23%)
TypeDoc	629	~478	23.0 ms	27.0 ms	+4.0 ms (17%)
Chart.js	739	~1,075	21.3 ms	23.7 ms	+2.4 ms (11%)
Svelte	3,235	~5,733	92.9 ms	89.7 ms	~0 ms (noise)

Absolute overhead is 0–6 ms across all repos. All repos format in under 93 ms with JSDoc enabled. On larger codebases like Svelte (5,733 JSDoc comments), the overhead is within noise margin.

Methodology

For each repo:

1. Shallow clone, install dependencies
2. Install prettier-plugin-jsdoc@latest, configure .prettierrc with printWidth: 80 and the plugin
3. Run npx prettier --write to create baseline, commit
4. Run oxfmt --write on same files
5. git diff to compare

Bugs Fixed in This Session

Three bugs were found and fixed during testing against evolu:

1. {@link} spurious space — {@link Buffer}-related → {@link Buffer} -related and {@link Foo}) → {@link Foo} ). Root cause: placeholders were restored before word wrapping, so tokenize_words split them into separate tokens with space inserted between.

2. {@link} over-aggressive wrapping — Lines with {@link ...} tokens wrapped earlier than Prettier because width was measured on the expanded text (14 chars for {@link Buffer}) instead of the placeholder (~7 chars). Root cause: same as above.

3. Embedded code formatting — JSON code blocks had quotes stripped ("scripts" → scripts), TypeScript generics mangled (createOrder<number> → createOrder < number >), plain text reformatted (64-bit → 64. Bit). Root cause: format_code_value() fell through to JS formatting for unknown languages and unlabeled code blocks.

Fix: Deferred all placeholder restoration to the end of the formatting pipeline (matching upstream behavior), and stopped formatting unknown-language/unlabeled fenced code blocks as JavaScript.