The body of a macro entirely defined on 1 line gets sucked into the synopsis

[duncan-roe]

Describe the bug
If the body of a macro definition is contained in a single line you don't get the separate Value: window. Instead the body of the macro is shown in the window with the macro parameters. man pages have the same fault: the body of the macro is shown as part of the synopsis.

Screenshots
In the screenshot below, I've circled in green how I think foo and bar should both display, and I've circled foo in red because it doesn't display that way.
Just noticed descriptions slightly different: fixed in the reproducer.

To Reproduce
Untar, cd reproducer then ./run.sh will display the generated man page. <your browser> html/index.html will show the HTML doc'n.
reproducer.tar.gz

Expected behavior
I would prefer if the body of a macro would always display in a Value: window. If the current behaviour is intentional, please can you treat this report as an enhancement request for a Doxyfile directive to make it work the way I prefer.

Version
Running under Slackware Linux 15.0. Have seen this behaviour in Slackware 14.2 doxygen 1.8.9.1 to latest snapshot 1.12.0 (14fc65f). Built that muself, 1.8.9.1 is from distributor.

[albert-github]

The shown output is intentionally, it is also the case for other instances.
Checkout the results of:

/**
 * the first var
 */
int x1[] = {1
  };

/**
 * the second var
 */
int x2[] =
  {1};

/**
 * the third var
 */
int x3[] = {1};

/**
 * the fourth var
 */
int x4[]
 = {1};

Example: example.tar.gz

@doxygen
We have the setting MAX_INITIALIZER_LINES that runs from 0 ... 10000 (for individual entities it can be further steered with \howinitilalizer and \hideinitializer). Maybe also negative numbers should be allowed for MAX_INITIALIZER_LINES having the same meaning as the positive value but in case the initializer line is just 1 line it will still be shown as initialization "block".
What do you think?

[albert-github]

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

[duncan-roe]

I tried adding \showinitializer to foo, but this does not put the 1-line body into its own box as I hoped it would.
reproducer2.tar.gz
My preference would be if showinitializer is updated to put the 1-line body into its own box.
Adding MAX_INITIALIZER_LINES = -30 to Doxyfile produces a warning
reproducer3.tar.gz
which only goes away at the next doxygen release; while adding \showinitializer has no effect until the next release, when it starts to do what I'm asking for.

[albert-github]

The \showinitializer command has as disadvantage:

• it is now an "on / off" switch so it would mean that the command would need an extra option to stay compatible with the current version
• the \showinitializer is not global but just for the one entry.

Regarding the negative sign,

• true that you cannot use the negative value in older versions, but it new, optional, features never can be used in older versions (there is the exception with some commands where one can use the command in older versions when one defines (i.e. removes) the command by means of an ALIASES)

Besides the negative number for the MAX_INITIALIZER_LINES I also thought about an extra setting, but there are already that many settings so I choose this implementation (though it would be easy the revert this implementation in favor of another settings. Another setting though has also the "disadvantage" that it can only be used in newer versions without a warning).

[duncan-roe]

AFAICS \showinitializer simply sets initLines to 100000 (at src/commentscan.l:3673). If it could set a marker that it had been used, then memberdef.cpp could take action on that marker. Sure that would change appearance if someone had coded \showinitializer for a 1-liner but is that a show-stopper?
It's fine with me that \showinitializer is local to the entry. I would expect to review generated documentation and insert \showinitializer as required.

[albert-github]

For me both points are show stoppers.

[duncan-roe]

point 1: Sure I'm proposing to change the behaviour of \showinitializer, but stuff changes all the time. F.I. we just went from Modules to Topics in 1.11. And dates disappeared from the bottom of man pages (at 1.9.x IIRC, thanks for that change btw). The currently advertised use for \showinitializer is to show multiple-line entries. How likely is it that anyone is using it on a single-liner?

point 2: Huh? You mean sentence starting It's fine with me? That's just my preference. Or were you referring to something else?

It's perhaps unfortunate that doxygen treats variable initializers and macro definitions the same way. 1-line macro definitions are typically longer than variable initializers and so more likely to benefit from being shown in an initialization "block".

[doxygen]

Maybe a simpler solution is to distinguish between function like macros and plain macros and treat function like macros always as multiline, e.g. given

#define PI          3.14152965
#define MAX(x,y)    ((x)>(y)?(x):(y))
#define MAX_ML(x,y) ((x)>(y)? \
                     (x):(y))

The macro PI would have 3.14152965 shown inline, whereas MAX's definition is shown in a separate "value" section, just like MAX_ML already would now. For variables, nothing will change.

[duncan-roe]

On Sun, Aug 04, 2024 at 04:27:38AM -0700, Dimitri van Heesch wrote: Maybe a simpler solution is to distinguish between function like macros and plain macros and treat function like macros always as multiline, e.g. given ```C++ #define PI 3.14152965 #define MAX(x,y) ((x)>(y)?(x):(y)) #define MAX_ML(x,y) ((x)>(y)? \ (x):(y)) ``` The macro `PI` would have 3.14152965 shown inline, whereas `MAX`'s definition is shown in a separate "value" section, just like `MAX_ML` already would now. For variables, nothing will change.

Hey I like that a LOT. Can you guys do it?