Doxygen can't document Global functions

[Yoshi-Nakai]

Describes bugs.

There are test.c and test.h, and static functions in test.c are documented in test.c.
The Global function is documented in the prototype declaration in test.h.

Until 1.9.4, the description of Global functions in both test.c and test.h html docs was the same.
From 1.9.5 onwards the content of the html document is different.
To get the same documentation for 1.9.5 and later, you need to explicitly add the @fn declaration to the prototype declaration in test.h.

Is this a specification change?
It is not realistic to rewrite the existing code according to the specification
Is there any workaround?

I'm not good at English, so I'm translating it with Google Translate. Sorry if there was a funny expression.

test.zip
change.

[albert-github]

This has to be investigated to give a good reasoning / answer, at first glance it looks like that the . The question is well understandable (google translate only didn't convert the OUTPUT_LANGUAGE = Japanese to OUTPUT_LANGUAGE = English 😉 😄 😄)

[albert-github]

I did some bisecting and it looks like it is an unexpected side effect of (2606d4e ):

2606d4e2e5c086d5fc5560099d2a417bf7ccf58c is the first bad commit
Date:   Thu Jul 21 18:36:05 2022 +0200

    Correction of line counting

    Based on a number of wrong error lines in CGAL some line counting has been corrected.
    - in case a formula contains a newline the newline will be missing in the resulting output  of commentscan (as the formula is replaced by an internal name), so the line number has to be adjusted
    - in case a `\noop` command ends by means of a `\ilinebr` the `\n` should not be written
    - in case a `\brief`command starts with empty lines these lines have to be counted and added to start position of the brief command (the empty lines themselves are not added

 src/commentscan.l | 20 ++++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

[doxygen]

@albert-github Seems like the lines

    addOutput(yyscanner,tmp);
    if (addToOutput) addOutput(yyscanner,yytext);

that are added to commentscan.l's endBrief() cause the issue (didn't check in detail why).
Do you have an example where these lines are needed to make the line counting correct?

[albert-github]

I came to the same conclusion and couldn't yet find a way around. Most likely the example with the PR #9465 has an example. I already tried a few things, before other issues surfaced that I wanted to have a look at. The solution I found worked except for the situation:

cgal_concept.h:8: warning: Found unknown command '\error_8'

where it gave

cgal_concept.h:9: warning: Found unknown command '\error_8'

Current in doxygen:

static void endBrief(yyscan_t yyscanner,bool addToOutput)
{
  struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
  if (!yyextra->current->brief.stripWhiteSpace().isEmpty())
  { // only go to the detailed description if we have
    // found some brief description and not just whitespace
    yyextra->briefEndsAtDot=FALSE;
    setOutput(yyscanner,OutputDoc);
    addIline(yyscanner,yyextra->lineNr);
    if (addToOutput) addOutput(yyscanner,yytext);
  }
  else
  {
    int saveLineNr = yyextra->lineNr;
    lineCount(yyscanner);
    yyextra->current->briefLine = yyextra->lineNr;
    yyextra->lineNr = saveLineNr;
  }
}

solution sofar

static void endBrief(yyscan_t yyscanner,bool addToOutput)
{
  struct yyguts_t *yyg = (struct yyguts_t*)yyscanner;
  if (!yyextra->current->brief.stripWhiteSpace().isEmpty())
  { // only go to the detailed description if we have
    // found some brief description and not just whitespace
    yyextra->briefEndsAtDot=FALSE;
    setOutput(yyscanner,OutputDoc);
    //addIline(yyscanner,yyextra->lineNr);
    if (yyextra->current->doc.stripWhiteSpace().isEmpty())
    {
      yyextra->current->docLine = yyextra->lineNr;
    }
    else
    {
      addIline(yyscanner,yyextra->lineNr);
    }
    if (addToOutput) addOutput(yyscanner,yytext);
  }
  else
  {
    int saveLineNr = yyextra->lineNr;
    lineCount(yyscanner);
    yyextra->current->briefLine = yyextra->lineNr;
    yyextra->lineNr = saveLineNr;
  }
}

I had the intention / intent to have a look in the coming week.

[doxygen]

@albert-github I think the problem comes from the combineDeclarationAndDefinition() function in memberdef.cpp which only copies the brief/detailed description of a member's declaration to its definition (and vise versa) when the target was empty (i.e. an empty string). With the change is it no longer an empty string but a string with empty lines and invisible commands.

So the solution directions could be

1. keep the strings empty as they were (and solve any line correction differently)
2. make the check for "empty doc string" more intelligent, i.e. take into account empty lines and \_iline commands as well.

I prefer 1) over 2) if possible, but an example where it doesn't work without adding the \_iline and newlines would help to better figure out what can be done.

[albert-github]

The fix as shown in #10238 (comment) nearly OK just missed the fact that the doc part should be really empty when resetting the counter). The remark about the "empty doc string" in #10238 (comment) triggered this idea.

I've just pushed a proposed patch, pull request #10249

[albert-github]

Code has been integrated in master on GitHub (please don't close the issue as this will be done at the moment of an official release).

[doxygen]

This issue was previously marked 'fixed but not released',
which means it should be fixed in doxygen version 1.9.8.
Please verify if this is indeed the case. Reopen the
issue if you think it is not fixed and please include any additional information
that you think can be relevant (preferably in the form of a self-contained example).