rust-lang / rust-lang/rustfmt

Using a markdown formatter for (doc) comments & wrapping

Open
#5,782 12 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-discussion
Dominant language
Rust
Stars
7k
Forks
1.1k
Avg merge
2d 13h
Merged PRs (30d)
24

Description

Are there any thoughts on using an off-the-shelf markdown formatter to handle doc comments? Specifically comrak which is quite popular and (I believe) has a compatible license.

Reasoning is that it seems like needs are slowly approaching a full markdown-aware formatter. Things like preserving list items (#5746) or maintaining table format are important but tricky to handle without one.

Just a sample from #5746, using comrak configured to line length 80 - note that text is wrapped but indentation and code are both preserved

Input:
//! - References?
//!   - Unsound. See this example:
//!     ```compile_fail
//!     # use core::mem::MaybeUninit;
//!     let mut a = 0;
//!     let b = maybe_uninit_ext::new::<&mut MaybeUninit<u8>>(&mut a);
//!     *b = maybe_uninit_ext::uninit();
//!     assert_eq!(a, 0); // undefined behavior! a is uninitialized.
//!     ```
//!     Due to interior mutability, this is an issue for immutable references
//!     as well.
//!
//!     Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean felis ipsum, mollis non
//!     malesuada quis, tincidunt a orci. Aliquam erat volutpat. Nullam dui diam, sollicitudin
//!     sed nulla ut, efficitur tempus mauris. Fusce consequat posuere nisl vitae consequat. Vivamus mattis porttitor sapien,
//!     sit amet interdum velit varius quis. Integer est dolor, interdum ultrices elementum
//!     vitae, porttitor sit amet ligula. Fusce ullamcorper sed velit nec dictum.

Output:
//! - References?
//!   - Unsound. See this example:
//!     ``` compile_fail
//!     # use core::mem::MaybeUninit;
//!     let mut a = 0;
//!     let b = maybe_uninit_ext::new::<&mut MaybeUninit<u8>>(&mut a);
//!     *b = maybe_uninit_ext::uninit();
//!     assert_eq!(a, 0); // undefined behavior! a is uninitialized.
//!     ```
//!     Due to interior mutability, this is an issue for immutable references as
//!     well. //\! Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean
//!     felis ipsum, mollis non malesuada quis, tincidunt a orci. Aliquam erat
//!     volutpat. Nullam dui diam, sollicitudin sed nulla ut, efficitur tempus
//!     mauris. Fusce consequat posuere nisl vitae consequat. Vivamus mattis
//!     porttitor sapien, sit amet interdum velit varius quis. Integer est dolor,
//!     interdum ultrices elementum vitae, porttitor sit amet ligula. Fusce
//!     ullamcorper sed velit nec dictum.

Edit with more context

Originally suggested at https://github.com/rust-lang/rustfmt/issues/3347#issuecomment-1493136462 because it seems like we do a lot of things that need to be markdown-aware (wrapping comments and doc comments, formatting doc comments), and doing this all manually seems more tedious than using a tool designed to do this exact thing.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading this proposal alongside issue #5746 and the referenced rustfmt discussion. Compare the requested doc-comment wrapping and Markdown preservation behavior with comrak's capabilities, then determine the project scope and acceptance criteria before implementation.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown, rust
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.