https://issues.dlang.org/show_bug.cgi?id=14413

--- Comment #1 from Kenji Hara <k.hara.pg@gmail.com> ---
(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.

--

https://issues.dlang.org/show_bug.cgi?id=14413

--- Comment #2 from Sönke Ludwig <sludwig@outerproduct.org> ---
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.

--

https://issues.dlang.org/show_bug.cgi?id=14413

--- Comment #3 from Kenji Hara <k.hara.pg@gmail.com> ---
(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.

--

https://issues.dlang.org/show_bug.cgi?id=14413

--- Comment #4 from Sönke Ludwig <sludwig@outerproduct.org> ---
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.

--

https://issues.dlang.org/show_bug.cgi?id=14413

Nick Sabalausky <cbkbbejeap@mailinator.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |cbkbbejeap@mailinator.com

--- Comment #5 from Nick Sabalausky <cbkbbejeap@mailinator.com> ---
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.

--

https://issues.dlang.org/show_bug.cgi?id=14413

--- Comment #6 from Nick Sabalausky <cbkbbejeap@mailinator.com> ---
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).

--

https://issues.dlang.org/show_bug.cgi?id=14413

--- Comment #7 from Nick Sabalausky <cbkbbejeap@mailinator.com> ---
Pull Request: https://github.com/D-Programming-Language/dmd/pull/4745

--

https://issues.dlang.org/show_bug.cgi?id=14413

Martin Nowak <code@dawg.eu> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |code@dawg.eu

--- Comment #8 from Martin Nowak <code@dawg.eu> ---
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.

--

https://issues.dlang.org/show_bug.cgi?id=14413

Walter Bright <bugzilla@digitalmars.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |RESOLVED
                 CC|                            |bugzilla@digitalmars.com
         Resolution|---                         |WONTFIX

--- Comment #9 from Walter Bright <bugzilla@digitalmars.com> ---
/// 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.

--

https://issues.dlang.org/show_bug.cgi?id=14413

Walter Bright <bugzilla@digitalmars.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
           Severity|normal                      |enhancement

--