Function prototype matching @fn command, but link between both is not made

[vincentdupaquis]

Hello,

I've been meeting an issue where I have a function which has a first set of doxygen comments in the same file, and a set of other ones in another file, using the @fn command to make the link between both.

I have attached a sample .h file showing the issue, function2 & function3 have the detail field recognized, while function1 does not.

The problem is linked to the fact that although both parameters between the function declaration & the @fn command are identical, in the failing case a parameter was declared "char* p1", and doxygen seems to memorize this parameter as "char *p1" (the space is not placed identically).

Best regards,
Vincent.

issue.zip
.

[albert-github]

From the provided Doxyfile I guess you use doxygen version 1.8.17 (please always mention the used version).

I tried it with the current version (1.9.3 (c0b9eaf)) and the current master (1.9.4 (dc29509)) as well and see the problem here too.

[albert-github]

Interesting to see that when using doxygen -d findmembers we see in the output:

findMemberDocumentation(): root->type='' root->inside='' root->name='void function1' root->args='(char <em>p1, char</em> p2)' section=8000000 root->spec=0 root->mGrpId=-1
findMember(root=000002B878C1F140,funcDecl='void function1(char <em>p1, char</em> p2)',related='',overload=0,isFunc=1 mGrpId=-1 #tArgList=0 spec=0 lang=200
findMember() Parse results:
  namespaceName=''
  className=``
  funcType='void'
  funcSpec=''
  funcName='function1'
  funcArgs='(char< em >p1, char</em > p2)'

instead of the expected:

findMemberDocumentation(): root->type=`' root->inside=`' root->name=`void function1' root->args=`(char *p1, char* p2)' section=8000000 root->spec=0 root->mGrpId=-1
findMember(root=000001C98DAF0090,funcDecl=`void function1(char *p1, char* p2)',related=`',overload=0,isFunc=1 mGrpId=-1 tArgList=0000000000000000 (#=0) spec=0 lang=200
findMember() Parse results:
  namespaceName=`'
  className=``
  funcType=`void'
  funcSpec=`'
  funcName=`function1'
  funcArgs=`(char *p1, char *p2)'
  funcTempList=`'
  funcDecl=`void function1'
  related=`'
  exceptions=`'
  isRelated=0
  isMemberOf=0
  isFriend=0
  isFunc=1

The difference is introduced in doxygen version 1.8.15 (the version 1.8.14 was still OK).

Further observations learn us that the problem is caused in the markdown processing.
When replacing (as of version 1.9.3!) the line:

@fn void function1(char *p1, char* p2)

by

@fn function1(char *p1, char* p2)

@doxygen

• This looks like a problem where also the second argument should not be processed by the Markdown processing or something has to be done because of the emphasis replacement.
• any idea how to solve?

[vincentdupaquis]

This issue is particularly frustrating, it took me one full day to understand (by which miracle ?) what was the root cause.
Why is there this mis-placed space, I do not know, but it is a pain for the one who meets the issue :(

[albert-github]

Dove a bit deeper in it.
The documentation of the @fn states:

\fn (function declaration)

where the (...) means till the end of the line.

Looks like the solution might be in:

 static const auto endOfFunc = [](const char *data_,int offset_,int size_) -> int

where it should be checked whether or not we reached the end of the line and no open bracket types (possibly also < ... > pairs).

Note that the function declaration of @fn can span multiple lines. like in:

/**
 * @brief My function 1
 *
 * @param p1 Parameter 1
 * @param p2 Parameter 2
 * @param p3 Parameter 3
 * @param p4 Parameter 4
 */
extern void function1(char p1, char p2, char p3, char p4);


/**
 * @fn void function1(char p1, char p2,
 * char p3, char p4)
 * @details Some more details about function 1
 */

[albert-github]

@vincentdupaquis
What do you mean by:

Why is there this mis-placed space,

i.e. which misplaced space, do you mean in your code or the fact that doxygen doesn't handle it properly ( I think doxygen should handle it properly though as char* p2 should / is equal the char *p2)

[vincentdupaquis]

I mean the space in the parameter p2, it should have been char *p2. We never write char* p2 :)

[doxygen]

The main problem is that @fn expects the function name plus arguments, but not the return type. Doxygen is normally robust if the return type is specified anyway, but the markdown processing was not yet.

[doxygen]

@vincentdupaquis Please verify if the referenced commit fixes the problem.

[albert-github]

I did some, multiline, tests as well and it looks OK to me.

[vincentdupaquis]

Hello,

I have tested with the project that was causing the original issue, and can confirm this fix is efficient !

Nice job :)

Best regards,
Vincent.