allow multi line doc strings

[20jasper]

#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]

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]

@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]

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]

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]

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]

correct!

[20jasper]

correct!

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

[Manishearth]

issue: please include a test for multiline attributes with ignore_extra_doc_attributes

[20jasper]

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]

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"

[Manishearth]

Yes, I think so.