Bug 14413 – Spurious newline in ddoc JSON output for multiple successive line doc comments

The following compiled with "dmd -X -D" results in an additional "\n" being inserted between the two doc lines. --- /// This function is here to aid in making your /// software do cool stuff. void foo() {} --- JSON: --- { "kind": "module", "file": "issue58_linedoc\\test.d", "members": [ { "kind": "function", "line": 5, "deco": "FZv", "endchar": 13, "char": 6, "name": "foo", "comment": "This function is here to aid in making your\n\nsoftware do cool stuff.\n", "endline": 5 } ], "name": "test" } ---

(In reply to Sönke Ludwig from comment #0) > --- > /// This function is here to aid in making your > /// software do cool stuff. > void foo() {} > --- It's equivalent with: --- /** This function is here to aid in making your software do cool stuff. */ void bar() {} --- DMD lexer concatenates the continuous ddoc line comments like paragraphs. The blank line is inserted to separate two one-liner paragraphs.

Do you know if that been a concious decision or is it just an artefact of the implementation? I don't think it makes much sense as it is. Personally I always use /** */ style comments, but anyone using /// is going to have issues with it.

(In reply to Sönke Ludwig from comment #2) > Do you know if that been a concious decision or is it just an artefact of > the implementation? I don't think it makes much sense as it is. Personally I > always use /** */ style comments, but anyone using /// is going to have > issues with it. At least http://dlang.org/ddoc says nothing about the case. It would be an artifact of the current dmd implementation, if there's no discussion in the old D forum (including digitalmars.d). But I think the "concatenation like paragraphs" is not bad.

Just that "concatenation as paragraphs" instead of "concatenation as lines" precludes the use of this documentation style: /// This is the summary, possibly going /// over multiple lines. /// /// A large paragraph /// of text also /// gets split /// /// --- /// as well as code blocks behave awkwardly /// --- But it seems like maybe not many have tried to use this style in the past.

I'm with Sonke on this. The output should match the input. If there isn't a blank line (ie paragraph break) in the doc comment, then one should NOT be added in the output. If I *DO* want a paragraph break in the output, I can trivially add one in the doc comment. I've had problems with the current behavior as I frequently use that comment style.

This is happening in function "Lexer::combineComments" in "lexer.c". The function combines consecutive doc comments, like: /++ comment 1 +/ /++ comment 2 +/ /** comment 3 */ /** comment 4 */ /// comment 5 /// comment 6 Note that the lexer treats each line of a line comment as a separate comment. Those all get combined and each one becomes a separate paragraph (by way of "Lexer::combineComments" concatenating them with an extra \n added in between each one). Ideally, IMO, "Lexer::combineComments" should only add the \n if there's at least one blank line between two comments. I'm not sure how feasable that is, but at the very least omitting the extra \n in between each would be an improvement, because I can't imagine that consecutive doc comments are really all that common, aside from the case in question here (immediately consecutive line comments).

Pull Request: https://github.com/D-Programming-Language/dmd/pull/4745

Well http://dlang.org/ddoc clearly states /// This is a one line documentation comment. /** So is this. */ and Multiple documentation comments applying to the same declaration are concatenated. So whatever method is used to concat multiple comments (and adding a '\n' between them seems sensible) should be used consistently.

/// This function is here to aid in making your /// software do cool stuff. is treated exactly the same way as: /** This function is here to aid in making your */ /** software do cool stuff. */ I.e. all three comment styles are treated the same way, as Martin suggested. I am very reluctant to change this because: 1. things would be no longer consistent 2. Ddoc has been in use for a very long time, and this could break an unknown large amount of existing code in a rather annoying fashion 3. There's an easy solution - use the multiline comment style for multiline comments, i.e. /** * This function is here to aid in making your * software do cool stuff. */ I.e. the breakage risk is high for a relatively small benefit. That's how it was designed to work.

The PR for this was merged (https://github.com/D-Programming-Language/dmd/pull/4745), so probably shouldn't be marked "WONTFIX" anymore.