Conversation
1ea65f3 to
b87cb54
Compare
comfort doc-comment formatter crate`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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
extractfinds doc-comment blocksvia
ra-ap-rustc_lexer,reflow_markdownparses each block's body withcomrak and walks the AST to locate reflowable paragraphs, and
reflow_paragraphsegments 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'sformat_commonmark(normalizes list markers to-, prefers fencedcode blocks, aligns table columns for visual display width including
CJK wide characters) before reflowing.
--reference-links: converts inline[text](url)links toreference-style
[text]with definitions consolidated and sortedalphabetically 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(directinvocation, defaults to stdin/stdout) and
cargo-comfort(cargosubcommand, defaults to
--workspace). Common flags:--check,--list-changed,--workspace,-p/--package,--exclude,--language,--stdin-filename,--max-width.A new
fmt-comments-cijustfile target runscomfort --check --workspacein CI, added to thecirecipe alongside the existingfmt-cistep.