Use `///` for all docs

[pvdrz]

Hi! Is there any reason why multi-line docs are formatted using /**?

For example, the following code:

#[doc = " This is a single line doc"]
pub type foo = ::std::os::raw::c_int;
#[doc = " This is a multi line doc.\n With way too many lines"]
pub type bar = ::std::os::raw::c_int;

is being formatted as

/// This is a single line doc
pub type foo = ::std::os::raw::c_int;
/** This is a multi line doc.
 With way too many lines*/
pub type bar = ::std::os::raw::c_int;

and I'd like it to be

/// This is a single line doc
pub type foo = ::std::os::raw::c_int;
/// This is a multi line doc.
/// With way too many lines
pub type bar = ::std::os::raw::c_int;

[jdygert-spok]

prettyplease maybe could fix this for you, but this is a consequence of how line doc comments are represented as separate doc attributes. These two are equivalent:

/// a
/// b
struct Foo;

#[doc = " a"]
#[doc = " b"]
struct Foo;

So as a result, if you want to generate line doc comments with quote, you can do something like this:

let doc = " a\n b";
let lines = doc.lines();
quote! {
    #( #[doc = #lines] )*
    struct Foo;
}

[dtolnay]

The rules for turning an arbitrary multi-line doc into multiple single-line doc, without breaking rustdoc's or markdown's interpretation of the text, is absurdly complicated. Eventually it would be good to develop logic to handle that but it will be an extremely involved change -- not a matter of .lines() in prettyplease.

[jdygert-spok]

Understood, the example above is just a workaround that is often usable "downstream".

[dtolnay]

Makes sense, thanks! Yeah it's a useful suggestion especially if someone is just concerned with a subset of possible markdown, such as paragraphs of text with no indented lists or code blocks.