Asciidoc: description for overload sets merged in single line for long Javadoc comments

[anarthal]

namespace repro {

/// A struct.
struct S
{
    /**
     * \brief Integer overload.
     * \details More info
     */
    void f(int) {}

    /**
     * \brief C string overload.
     * \details More info
     */
    void f(const char*) {}
};

}  // namespace repro

Renders:

Merging two distinct descriptions in a single paragraph is confusing.

If we use the brief-only Javadoc format, things work:

namespace repro {

/// A struct.
struct S
{
    /// Integer overload.
    void f(int) {}

    /// C string overload.
    void f(const char*) {}
};

}  // namespace repro

[alandefreitas]

Mmm... While making this explicit, that's a good opportunity to include an alternative to https://www.doxygen.nl/manual/config.html#cfg_javadoc_autobrief in MrDocs. I've been relying on automatic briefs so far and that's the only thing we use.

[anarthal]

Hm some of my briefs are long enough for autobriefs not to work. This happens with enumerators - IIRC only the brief description is ever shown, so I need \brief for this. But enums are not affected by this, so I could just migrate the others.

However, \brief should definitely do the same as autobriefs.

[alandefreitas]

MrDocs considers the first paragraph to be the auto-brief, no matter how long it is. Maybe doxygen only considers the first line. I'll make a better comparison.

[anarthal]

Yep, that's not what Doxygen does. From the link you posted:

" If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen will interpret the first line (until the first dot, question mark or exclamation mark) of a Javadoc-style comment as the brief description."

[anarthal]

Not saying it needs to be like this, MrDocs behaviour makes sense.

Out of curiosity, why does \brief behave differently to automatic briefs?

[alandefreitas]

Out of curiosity, why does \brief behave differently to automatic briefs?

I still have to debug this one. :)

[alandefreitas]

Yes. So JAVADOC_AUTOBRIEF only considers the first line. But the first "line" is defined as the content until the first dot, question mark or exclamation mark.

All other alternatives (/brief with Doxygen or Clang, or MrDocs) consider the first paragraph.

[anarthal]

I think it makes much more sense to consider the first paragraph.
I like being explicit, so I went with \brief.