Skip to content

chore(comfort): Add semantic line-break Rust/Markdown formatter#663

Merged
JeanMertz merged 1 commit into
mainfrom
prr230
May 25, 2026
Merged

chore(comfort): Add semantic line-break Rust/Markdown formatter#663
JeanMertz merged 1 commit into
mainfrom
prr230

Conversation

@JeanMertz
Copy link
Copy Markdown
Collaborator

@JeanMertz JeanMertz commented May 20, 2026

comfort is a new contrib crate that reformats Rust doc comments (///and//!) and Markdown files using semantic line breaks — one sentence per line — with an optional --max-width` safety net for long sentences.

The pipeline runs in three layers: extract finds doc-comment blocks
via ra-ap-rustc_lexer, reflow_markdown parses each block's body with
comrak and walks the AST to locate reflowable paragraphs, and
reflow_paragraph segments those paragraphs into sentences using a UAX
#29 splitter with abbreviation-aware merging.

Markdown structure (headings, code blocks, tables, block quotes, lists,
footnotes, hard line breaks) is preserved verbatim; only prose paragraph
contents are reflowed. Container blocks (block quotes, list items, task
items, alerts, footnote definitions) each contribute the correct
per-line continuation prefix so reflow output round-trips cleanly.

Two optional passes compose on top of the always-on sembr engine:

  • --format-markdown: canonicalizes markdown structure via comrak's
    format_commonmark (normalizes list markers to -, prefers fenced
    code blocks, aligns table columns for visual display width including
    CJK wide characters) before reflowing.
  • --reference-links: converts inline [text](url) links to
    reference-style [text] with definitions consolidated and sorted
    alphabetically at the bottom of each body.

Both transformations are idempotent individually and when composed.

The tool ships two binaries from the same entry point: comfort (direct
invocation, defaults to stdin/stdout) and cargo-comfort (cargo
subcommand, defaults to --workspace). Common flags: --check,
--list-changed, --workspace, -p/--package, --exclude,
--language, --stdin-filename, --max-width.

A new fmt-comments-ci justfile target runs comfort --check --workspacein CI, added to theci recipe alongside the existing
fmt-ci step.

@JeanMertz JeanMertz force-pushed the prr230 branch 2 times, most recently from 1ea65f3 to b87cb54 Compare May 22, 2026 07:56
@JeanMertz JeanMertz changed the title build(comfort): Add comfort doc-comment formatter crate chore(comfort): Add semantic line-break formatter for doc comments May 22, 2026
`comfort` is a new contrib crate that reformats Rust doc comments (`///`
and `//!`) and Markdown files using semantic line breaks — one sentence
per line — with an optional `--max-width` safety net for long sentences.

The pipeline runs in three layers: `extract` finds doc-comment blocks
via `ra-ap-rustc_lexer`, `reflow_markdown` parses each block's body with
comrak and walks the AST to locate reflowable paragraphs, and
`reflow_paragraph` segments those paragraphs into sentences using a UAX
#29 splitter with abbreviation-aware merging.

Markdown structure (headings, code blocks, tables, block quotes, lists,
footnotes, hard line breaks) is preserved verbatim; only prose paragraph
contents are reflowed. Container blocks (block quotes, list items, task
items, alerts, footnote definitions) each contribute the correct
per-line continuation prefix so reflow output round-trips cleanly.

Two optional passes compose on top of the always-on sembr engine:

- `--format-markdown`: canonicalizes markdown structure via comrak's
  `format_commonmark` (normalizes list markers to `-`, prefers fenced
  code blocks, aligns table columns for visual display width including
  CJK wide characters) before reflowing.
- `--reference-links`: converts inline `[text](url)` links to
  reference-style `[text]` with definitions consolidated and sorted
  alphabetically at the bottom of each body.

Both transformations are idempotent individually and when composed.

The tool ships two binaries from the same entry point: `comfort` (direct
invocation, defaults to stdin/stdout) and `cargo-comfort` (cargo
subcommand, defaults to `--workspace`). Common flags: `--check`,
`--list-changed`, `--workspace`, `-p`/`--package`, `--exclude`,
`--language`, `--stdin-filename`, `--max-width`.

A new `fmt-comments-ci` justfile target runs `comfort --check
--workspace` in CI, added to the `ci` recipe alongside the existing
`fmt-ci` step.

Signed-off-by: Jean Mertz <git@jeanmertz.com>
@JeanMertz JeanMertz changed the title chore(comfort): Add semantic line-break formatter for doc comments chore(comfort): Add semantic line-break Rust/Markdown formatter May 25, 2026
@JeanMertz JeanMertz merged commit 3ff5a41 into main May 25, 2026
14 checks passed
@JeanMertz JeanMertz deleted the prr230 branch May 25, 2026 12:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant