empty line bug in mardown comments

[ghost]

Empty lines seem to finish the comment:

/**
 * # This
 * ## is
 * ### a md comment
 * _TextAlign_ enumerates the possible alignment ***kinds***
 * cf [this article](http://www.nowhere.org/doc.htm)
 * * _left_: align to left
 * * _center_: align to center
 * * _right_: align to right
 * 
 * Note: this has no effect when the input text length exceeds _maxCol_
 * Yo.
 */
enum TextAlign {left, center, right}

produces

Or maybe the leading ***** are the cause ?

[kiith-sa]

I could reproduce this in enum summaries, and probably summaries of at least all aggregates, but not in e.g. module summaries. Not sure yet as to what is the cause, but readAndWriteComment() seems to "forget" that part of the text (at least for enum).

[kiith-sa]

OK, this not really an issue. libddoc treats the first text block without newlines as the first section, which is used as a non-detailed summary in the Enums: table here. This is also described in the DDoc documentation

Other sections (such as Note: there) are only used in the detailed documentation (behind the TextAlign link here). So this is not really a bug, but it is confusing.

So to have a 'canonical' comment, you could do:

/** Summary describing the enum here (usually this is just one line)
 * Second line of the summary
 * This is still in summary
 *
 * This is not in summary
 * 
 * Not summary either:
 *
 * Some more non-summary content
 */

If you want full comment text to be in the Enums: table, that is not supported at the moment. I'm planning (#21) to eventually add a feature to automatically include small comments (often variable comments) so we don't generate HTML files with one line of content, and that will be tweakable to even include everything. But I'm not going to do it in near future because of time constraints and I'd rather spend any harbored-mod time on refactoring fixing bugs.

[ghost]

Ok, I understand, my bad.