Using a markdown formatter for (doc) comments & wrapping
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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