Suppress periods from ending brief description in JAVADOC_AUTOBRIEF

Question

The JAVADOC_AUTOBRIEF setting seems a very nice convenience, so that instead of writing:

/// \brief Brief description.
///        Brief description continued.
///
/// Detailed description starts here.

You can write:

/// Brief description; brief description continued.
///
/// Detailed description starts here.

Yet where I have used the ; here to merge content into a single sentence, I would like to have the option of somehow preventing a period from ending the brief description.

When I went to poke through the source a little, I found a suggestion that you could get around this precise problem by escaping the period. However: /// Brief description\. Brief description continued. did not work for me.

Based on that suggestion, what appeared to work instead was "escaping the space" as /// Brief description.\ Brief description continued. I'm not convinced that's an actual "feature" of doxygen, and I just confused it and it ignored an error state.

• Can anyone confirm for me that the documentation is incorrect about \. space being used for this purpose? (If so, does anyone involved with doxygen who followed the tag here want to file the report about that?)

• If \ (backslash-space) isn't an approved way to escape space, then is there an endorsed way? I tried several things it didn't like... such as ..

Answer 1

I believe that you will get the behavior you desire if you set MULTILINE_CPP_IS_BRIEF to YES, and then set both JAVADOC_AUTOBRIEF and QT_AUTOBRIEF back to NO.

I have to set this for all of my projects because I am excessively prolix. It allows me to write multiple sentences—and even span multiple lines—within a "brief" description without doxygen cutting me off.

The drawback is that you must skip a line between your multi-line brief description and the beginning of your always-multi-line detailed description. Obviously, that's how it knows when one begins and another ends.

Anyway, you can now write stuff like this:

/// Returns the alpha channel value of this color, represented as a percentage.
/// A value of 0% means completely transparent, while 100% means fully opaque.
/// 
/// According to [Wikipedia](https://en.wikipedia.org/wiki/Alpha_compositing),
/// the concept of an alpha channel was first introduced by Alvy Ray Smith in
/// the late 1970s, and fully developed in a 1984 paper by Thomas Porter and
/// Tom Duff. In a 2D image element, which stores a color for each pixel, the
/// additional transparency data is stored in the alpha channel...
/// @return  Returns a percentage from 0 (completely transparent) to 100 (fully opaque)
///              that indicates the color's alpha channel transparency.
/// @see SetAlpha() to set a new alpha channel value
int GetAlpha() const;

And get output like this:

Returns the alpha channel value of this color, represented as a percentage. A value of 0% means completely transparent, while 100% means fully opaque.

According to Wikipedia, the concept of an alpha channel was first introduced by Alvy Ray Smith in the late 1970s, and fully developed in a 1984 paper by Thomas Porter and Tom Duff. In a 2D image element, which stores a color for each pixel, the additional transparency data is stored in the alpha channel...

No escaping required! You can use this on functions, classes, namespaces, or whatever. The entire multi-line brief description even shows up in the big tables (e.g., like you see on the page listing all namespaces in a project).

Answer 2

Based on that suggestion, what appeared to work instead was "escaping the space" as /// Brief description.\ Brief description continued. I'm not convinced that's an actual "feature" of Doxygen

It's an official feature documented in the manual:

If you enable this option and want to put a dot in the middle of a sentence without ending it, you should put a backslash and a space after it. Here is an example:

/** Brief description (e.g.\ using only a few words). Details follow. */

I've filed a bug report (Bugzilla #782373) for the documentation about \..