allow multi line doc strings by 20jasper · Pull Request #57 · yaahc/displaydoc

20jasper · 2025-12-13T06:35:22Z

#44 requests multi line doc strings, and I've also wanted this myself, so figured may as well!

Since multiple doc comments caused a panic prior, this is backwards compatible. If #[ignore_extra_doc_attributes] is there, the first doc ident continues to be displayed, otherwise each doc comment is joined by newlines

The first doc comment is used as the span

closes #44

Manishearth · 2025-12-19T00:27:07Z

I don't think this is correct: we definitely don't want newlines in Display impls.

Allowing line wrapping seems good, though. What if we make a minimal change: allow multiline doc comments, but only when the lines are not empty (which creates a paragraph break in Markdown). In those cases, we still error as we do now.

Separately, we can see what people think is the most logical choice in those cases. Perhaps we could have an attribute that lets you pick between "insert newline" or "ignore everything after the paragraph break". I don't know, but that's a more involve discussion that needs to happen, and I don't want to block getting the newline problem fixed on that.

20jasper · 2025-12-19T00:40:02Z

@Manishearth Makes sense! I went off of the example in #44, which used newlines. Off the top of my head, clap concatenates with spaces with multiple lines of doc comments, for example

        /// Removes all insignificant whitespace instead of pretty printing,
        /// also known as minifying. Cannot be combined with --preferred-width
        #[arg(short, long, conflicts_with = "preferred_width")]
        uglify: bool,

  -u, --uglify
          Removes all insignificant whitespace instead of pretty printing, also known as minifying. Cannot be combined with --preferred-width

I believe argh also concatenates with spaces and rustdoc preserves line breaks

20jasper · 2025-12-19T00:41:07Z

To be clear, you are interested in what I have now with multiline doc comments, but error on empty lines, right? For example

/// all
/// good!
struct CoolStruct;

/// multi paragraph
/// 
/// Not allowed
struct CoolStruct;

Manishearth · 2025-12-19T00:43:26Z

Yes, and the first one should produce the string all good!. The second one should have the same behavior as now, along with the "ignore multiline" attribute

20jasper · 2025-12-19T00:47:26Z

Ah! I wasn't on the same page there, is this in line with what you're thinking?

1.) Outputs "all good!"

/// all
/// good!
struct CoolStruct;

2.) error, multiline is not allowed

/// multi paragraph
/// 
/// Not allowed
struct CoolStruct;

3.) "multi paragraph"

#[ignore_extra_doc_attributes]
/// multi paragraph
/// 
/// Not allowed
struct CoolStruct;

Manishearth · 2025-12-19T00:49:52Z

correct!

20jasper · 2025-12-19T02:02:35Z

correct!

Updated! Fixed up the example and the documentation as well. Let me know if you have anything else you'd like changed

Manishearth · 2025-12-19T20:26:12Z

+#[derive(Display)]
+/// Really fancy first line with thing: {thing}
+/// Really cool second line
+struct HappyMultiLine {


issue: please include a test for multiline attributes with ignore_extra_doc_attributes

20jasper · 2025-12-19T22:24:17Z

+#[derive(Display)]
+#[ignore_extra_doc_attributes]
+/// multi
+/// line
+///
+/// new paragraph should be ignored
+struct HappyMultilineWithIgnore;


issue: please include a test for multiline attributes with ignore_extra_doc_attributes

Good callout! Here's a new test covering that case

Output is "multi line"

20jasper · 2025-12-19T22:49:44Z

+    /**
+     * block
+     * comment
+     */
+    /**
+     * block
+     * comment2
+     */
+    DoubleBlock,


I just added test cases for several other edge cases

Question—is it appropriate to concatenate sequential block comments with spaces?

This outputs "block\ncomment block\ncomment2"

Yes, I think so.

Just checking in if there's anything I'm missing to push this across the finish line. Please let me know if you'd like any changes!

I'm on vacation right now and previously I had hit the limit of the amount of time I wanted to spend on an optional feature for displaydoc. I'll get around to this eventually.

No problem. I appreciate the directness. Enjoy your vacation!

Manishearth · 2026-01-20T19:51:23Z

+        } else {
+            strs.collect::<Option<Vec<_>>>()
+        }.unwrap_or_else(|| {
+            panic!("Line breaks in multi-line doc comments are disabled by default by displaydoc. Please consider using block doc comments (/** */) or adding the #[ignore_extra_doc_attributes] attribute to your type next to the derive");


nit: should be double line breaks, i think, since single line breaks are now allowed.

Manishearth

Should be good with one nit

Manishearth · 2026-01-20T19:52:31Z

Actually I'll merge as is and fix up the panic message myself. Thanks!

20jasper force-pushed the 44-multi-line-doc-strings branch 3 times, most recently from 9aea6c3 to 1c1e8f0 Compare December 19, 2025 00:25

20jasper force-pushed the 44-multi-line-doc-strings branch 3 times, most recently from dc022d8 to 7726201 Compare December 19, 2025 01:54

20jasper force-pushed the 44-multi-line-doc-strings branch from 7726201 to d9a92b3 Compare December 19, 2025 02:10

Manishearth reviewed Dec 19, 2025

View reviewed changes

20jasper commented Dec 19, 2025

View reviewed changes

Comment thread tests/ui/multi_line_allow.rs

20jasper force-pushed the 44-multi-line-doc-strings branch from d9a92b3 to c500245 Compare December 19, 2025 22:22

20jasper commented Dec 19, 2025

View reviewed changes

20jasper force-pushed the 44-multi-line-doc-strings branch 2 times, most recently from 63ce708 to e561494 Compare December 19, 2025 22:47

allow multi line doc strings

e561494

20jasper commented Dec 19, 2025

View reviewed changes

Manishearth reviewed Jan 20, 2026

View reviewed changes

Manishearth approved these changes Jan 20, 2026

View reviewed changes

Manishearth merged commit aeeed8c into yaahc:master Jan 20, 2026
8 checks passed

Conversation

20jasper commented Dec 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Manishearth commented Dec 19, 2025

Uh oh!

20jasper commented Dec 19, 2025

Uh oh!

20jasper commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Manishearth commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

20jasper commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Manishearth commented Dec 19, 2025

Uh oh!

20jasper commented Dec 19, 2025

Uh oh!

Manishearth Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

20jasper Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

20jasper Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

Manishearth Dec 19, 2025

Choose a reason for hiding this comment

Uh oh!

20jasper Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

Manishearth Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

20jasper Jan 19, 2026

Choose a reason for hiding this comment

Uh oh!

Manishearth Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Manishearth left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Manishearth commented Jan 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

20jasper commented Dec 13, 2025 •

edited

Loading

20jasper commented Dec 19, 2025 •

edited

Loading

Manishearth commented Dec 19, 2025 •

edited

Loading

20jasper commented Dec 19, 2025 •

edited

Loading

20jasper Dec 19, 2025 •

edited

Loading