Colon on a line by itself

[paul-j-lucas]

Describe the bug
With source like this:

/**
 * Flag for c_ast_gibberish() to indicate that the declaration is for multiple
 * objects, e.g.:
 *
 *      int *p, *q;
 */

it generates HTML where the : is put on a line by itself — see screenshot. If the e.g.: is changed to for example:, it works as expected. I suspect that Doxygen sees the . and thinks it's the end of the sentence and hence the "brief" description.

Expected behavior
I expect the : to remain next to the e.g..

Screenshots

Version
1.9.3
macOS 12.3.1
Doxygen via MacPorts.

[albert-github]

Although there are no doxygen settings provided it looks like that the setting of JAVADOC_AUTOBRIEF is YES.

• Is it on purpose that you have JAVADOC_AUTOBRIEF = YES?

When disabling this it works all as you expected.

[doxygen]

Another option is to use:

/**
 * Flag for c_ast_gibberish() to indicate that the declaration is for multiple
 * objects, e.g.\ :
 *
 *      int *p, *q;
 */

but since ending a brief description with e.g. doesn't really make sense the better solution is to use

/**
 * Flag for c_ast_gibberish() to indicate that the declaration is for multiple
 * objects.
 *
 * Example:
 * 
 *      int *p, *q;
 */

[albert-github]

@doxygen How about extending in commentscan.l (around line 951) the rule:

<Comment>".,"                           { // . with comma such as "e.g.,"
                                          addOutput(yyscanner,yytext);
                                        }

to

<Comment>"."[,:;]                           { // . with comma such as "e.g.,"
                                          addOutput(yyscanner,yytext);
                                        }

Another point here is that currently the rules regarding the end of brief are all regarding a dot (.), but shouldn't this be extended to question marks (?) and exclamation marks (!) ?

[paul-j-lucas]

Is it on purpose that you have JAVADOC_AUTOBRIEF = YES?

Yes, because I hate typing @brief all over the place.

... since ending a brief description with e.g. doesn't really make sense ...

It makes sense to me.

The proposal for <Comment>"."[,:;] seems reasonable to me.

Another point here is that currently the rules regarding the end of brief are all regarding a dot (.), but shouldn't this be extended to question marks (?) and exclamation marks (!) ?

Maybe. If you were processing text in general and you needed to find the end of a sentence, then I'd say yes; but this case is specifically for auto-brief. I can't really see brief descriptions being questions or exclamations (shouting at the reader). OTOH, it's not clear adding !? would hurt anything either.

[doxygen]

@paul-j-lucas What I meant with "doesn't make sense" is that the brief description is also used as a standalone text at other places, like overviews and tooltips. So for instance the function overview will look like this:

The "More..." link may still make it look ok-ish but I hope you get my point.

@albert-github I don't have a problem with the suggested fix.

[paul-j-lucas]

Yes, I understand. Personally, I think it's fine.

[albert-github]

Regarding the problem with the colon I've just pushed a proposed patch, pull request #9311

[albert-github]

Code of pull request #9311 has been integrated in master on GitHub.

The problem regarding the ? And ! will be handled in another pull request.