index.html ignores brief documentation for enumerations

[rhdunn]

Given:

enum class Color { Red, Green, Blue };

and associated documentation like:

#<cldoc:Color>

Describes a system color.

These colors are assocated with CSS-style `RGB` values of the form `#RRGGBB`.

#<cldoc:Color::Red>

Specifies a bright red color.

This has the value `#FF0000`.

Here, the first line is placed in brief documentation with the rest in the doc section. When viewed using index.html, the brief section is ignored, so you get:

enum class Color
| These colors are assocated with CSS-style `RGB` values of the form `#RRGGBB`.

Red   : 0 : This has the value `#FF0000`.
Green : 1 : This has the value `#00FF00`.
Blue  : 2 : This has the value `#0000FF`.

This makes it difficult to document specifics for an enumeration/enumeration value (referencing external specifications, detailing usage, giving examples, etc.).

[jessevdk]

Actually, what happens is that Specifies a bright red color. is set as the brief doc, and This has the value #FF0000 is the full doc. This is no different than any other element. For the rendering, the full doc is shown if present, otherwise it is the brief doc. You should always write the full doc self-contained (i.e. should not depend on the brief doc being presented).

[rhdunn]

I have modified the defect to reflect that it is with rendering index.html -- you ninja'd your comment :).

Doxygen places the brief description before the detailed documentation for the full documentation sections so you don't have to repeat the brief description.

[jessevdk]

cldoc != doxygen

[rhdunn]

Fair enough. I was pointing it out as it is something that will trip people up when converting documentation from doxygen to cldoc. It will also likely lead to duplicated lines in the documentation.

Part of the problem I am having in this respect is the lack of detailed documentation on the way cldoc documentation comments are formatted and interpreted.

[jessevdk]

For 1) cldoc was not really intended for conversion of doxygen, more for new projects. I don't think keeping the brief and full doc independent leads to much duplication. Brief documents are, well, brief. A single sentence without details. Making them independent leads to more readable documentation, since the full doc does not need to flow with the brief doc.

2. Sure, although I think you're mostly just biased by Doxygen, and cldoc follows different conventions. That said it's a valid point, since most people will know Doxygen and have the same bias.