rustdoc: consecutive single-line docstrings should be concatenated

[ghost]

If document strings for rustdoc are written as a sequence of single line comments (i.e. ///) then rustdoc only uses the first line. The whole sequence should be joined to form a single attribute for further processing.

[Dretch]

I would be happy to have a look at this (I guess maybe I caused the issue).

[Dretch]

It seems like one way to fix this issue would be to have rustdoc concatenate all doc-attributes/doc-comments for an item and use the concatenated text as if it were from a single doc-attribute/comment.

Currently rustdoc discards all but the first doc-attribute, and emits a warning that the others were discarded. However the warning is emitted using warn!(...) which means it doesn't actually display to the user unless they have turned on warn logging for rustdoc, which seems unlikely.

Would this approach (concatenating all doc-comments) be ok?

[Dretch]

Another approach would be to change the lexer so that it parses multiple adjacent lines that all start with /// as a single doc-comment.

[brson]

@Dretch Having rustdoc concatenate the attributes sounds good to me.

[ghost]

@Dretch You're right, I ran rustdoc without warnings being logged.
Are you referring to fn doc_meta in attr_parser.rs? That looks like it would be a sensible place to do the concatenation.

[Dretch]

@peterhull90

Are you referring to fn doc_meta in attr_parser.rs? That looks like it would be a sensible place to do the concatenation.

Yup. See the pull request - it makes multi-line /// comments work the same as /** ... */ comments (as a side effect of concatenating all kinds of doc-comment).

Unfortunately multi-line comments seem a bit broken in general with rustdoc. In html output mode they are concatenated into a single line (I think due to some weirdness with pandoc).

[brson]

Fixed by @Dretch