include command via ALIASES does not work anymore

[alfish2000]

Describe the bug
Include additional documentation via the \include command handled via an ALIASES in the DoxyGen-Cfg-File is not shown properly in doxygen 1.10.0.

Expected behavior
The expected output is generated by doxygen 1.9.6 by utilizing the “Doxyfile196.cfg” configuration for the identical input content.

Screenshots
No screenshot, as they generate no further e.g. warnings.

To Reproduce
DoxyGen1100.zip
In the file AppInit.c in the documentation for “Function3” (Line 44-53) the native doxygen commands used to insert the additional information (markdown table) from the “LibOp1_LibOp1_RunFct.doxinclude” file.
This is shown appropriately in doxygen 1.10.0.

In contrast the documentation for “Function4” (Line 59-66) utilizes the ALIASES capability to perform the identical step.
But this is not shown appropriately in doxygen 1.10.0.
Utilizing the identical with doxygen 1.9.6 (“Doxyfile196.cfg”) the results are shown correctly.

The ALIASES are identical for the doxygen versions.

Version
Windows10/11 (64 bit), Doxygen 1.10.0.

Stack trace
No crash

Additional context
na

[albert-github]

This is an unfortunate side effect from the fact that the \include{doc} is now resolved in an earlier stage of the doxygen process (i.e. the commentcnv), where also the ALIASES are translated.
The advantage is that we get a better handling of the included code but side effect is that the \include{doc} is not handled properly.
This conversion is not recursive and the \include{doc} from the ALIASES is handled as a "regular" \include.

@doxygen

• maybe we should use here a more recursive approach?

or

• should we mention this in the documentation as an exception?

[doxygen]

@albert-github A recursive approach would be best.

We could try to push back the result of ALIAS expansion if it contains a \include{doc}.
We have to be careful to avoid infinite recursion, i.e. something simple as

ALIASES = "note=\note Prefix:"

Would keep on expanding if pushed back.

[albert-github]

Indeed recursive parts can spoil the party.
I think that for ALIASES, \include{doc}, and \snippet{doc} during the "recursive" evaluation a list must be kept with already expanded entities and when the same entity appears again a warning must be given and the replacement process should be stopped.
It might be necessary to think about the given example:

ALIASES = "note=\note Prefix:"

as this is a nice example where the substitution is currently valid and I think it should stay valid as well.

An example of it is:

\note A note

> [!note]
> A GitHub Alert note

I added also the GitHub Alert here to show that this is not affected by the ALIASES as the output is:

All in all a complex problem.

[doxygen]

@alfish2000 Please verify if the referenced commit fixes the problem for you. Do not close the issue, this will be done automatically when the next official release becomes available.

[alfish2000]

Thank you for your quick response and for the quick fix.
It seems to work for the first example I've posted.

Sadly the fix does not work in some of our other scenarios.
I've added a new example DoxyGen1100v2.zip which still does not work.

Two additional observations can be seen there (in AppInit.c):

• The /par topic is added but the rest is missing see "Function5(...)"
• Part from the “ALIASES” are displayed in the documentation see "Function6(...)"

[albert-github]

There have been some improvements yesterday, which version did you exactly use (i.e. doxygen -v)

You mean that to Function5 the

is added and to Function6::

I did a quick run with doxygen -d commentcnv and here we see for the Function5:

int Function5(int i)
{
        /// \anchor anchor_LibOp1_LibOp1_RunFct  \ilinebr \ifile ".../LibOp1_LibOp1_RunFct.doxinclude" \iline 1 \ilinebr \par Guidelines
<table><tr><th>ID</th><th>Category</th><th>Guideline</th></tr>
<tr><td><b>OSXXXX010</b></td><td align="center">\link ref_text_BASIC <b>\htmlonly<font size="2" color="blue">BASIC</font>\endhtmlonly</b>\endlink</td><td>
     \p This is the first text, which using #Function2
</td></tr>
<tr><td><b>OSXXXX20</b></td><td align="center">\link ref_text_BASIC <b>\htmlonly<font size="2" color="blue">BASIC</font>\endhtmlonly</b>\endlink</td><td>
     \p This is the next text
</td></tr>
<tr><td><b>OSXXXX200</b></td><td align="center">\link ref_text_CAN <b>\htmlonly<font size="2" color="green">CAN</font>\endhtmlonly</b>\endlink</td><td>
     This call may be skipped text, in order for #Function1 directly.
     In such a use case text for a function,
     so reference to #Function2 should be considered.
</td></tr>
</table>

\par Application Notes
The following application notes show the usage of Fct
- \link Function1 \endlink
 \ilinebr \ifile ".../AppInit.c" \iline 80

        return(i);
}

notice the missing /// before the expanded lines.

Btw did you notice the warning:

.../AppInit.c:80: warning: multiple use of section label 'anchor_LibOp1_LibOp1_RunFct' while adding anchor, (first occurrence: .../AppInit.c, line 64)

[alfish2000]

We have tried the version mentioned above:
1.11.0 (1099c80*)

But this one behaves equal:
https://github.com/doxygen/doxygen/actions/runs/7804759481/job/21287453536
1.11.0 (50d1776*)

Or is there an even newer version?

The warning can be removed if Function4(...) is removed completely.
It just came in because we quickly extended the first sample with Function5 and Function6

In Function5() there is only the word "Guidelines" and the rest is missing.

In Function6() the rest is present but the "Guidelines" word is missing and instead there is some non-processed text.

[albert-github]

Or is there an even newer version?

No not yet.

[albert-github]

Some observations / thoughts:

I thought this issue over again and in the doxygen documentation of the \include command there are 2 interesting statements:

Using the \include command is equivalent to inserting the file into the documentation block and surrounding it
with \code and \endcode commands.

and

The included documentation should not have comment signs in it as they will appear in the documentation as
well.

and in the past this was correct and is still correct for the \include statement except for the \include{doc}. The later is due to the place where nowadays the \include{doc} is evaluated.

Just placing some /// in front is not sufficient as this will not catch the line added by doxygen regarding the "jump back" (i.e. \ifile and \iline).
also the first line of the the included file should be empty.

In case of a /** ... */ type of comment all looks like to be OK but this is due to the fact that the part of the lines * are optional (though it can still be disruptive due to a change in indentation level.

All in all quite complex.

[thom-sch]

Hello,
I run into the same problem with \snippet{doc}.
Trying the deprecated variant \snippetdoc as a workaround doesn't solve the problem.

Now there is the question whether doxygen could handle these commands as a workaround?

Regards from Meerbusch
Thomas Schneider

[albert-github]

@alfish2000 Does the problem still occur with the current doxygen version (1.11.0), if so please show what you see and what you expect

@thom-sch Does the problem still occur with the current doxygen version (1.11.0), if so please show what you see and what you expect including a test project (attach a, small, self contained example (source+configuration file in a, compressed, tar or zip file!) that allows us to reproduce the problem? Please don't add external links as they might not be persistent (also references to GitHub repositories are considered non persistent)).