Possible to get enum values in the Enumeration Type documentation?

[bitblitz]

Not sure if this is a bug, or a feature request, or user error.

Describe the bug
Given something like the example shown below, the generated documentation for foo.h has two sections regarding this enumeration.

The first section "Enumerations" contains the values, such as:

enum | RequestFlags {  FIRST = 0x01, ...

The number of values per line are controlled by the ENUM_VALUES_PER_LINE setting.

The second section "Enumeration Type Documentation" contains a table such as this:

enum RequestFlags
Valid Request Flags

Enumerator
| FIRST | ONE
etc...

This second detailed table contains the actual description text from the code.

Is it possible to get the actual numeric value from the "Enumerations" description included in this table? Is there a setting that controls that, or is this a feature request?

Expected behavior
Expect the value to be included in the detailed description of enums, or a setting to optionally include it in the detailed table.

Screenshots
attached

To Reproduce

/// @file foo.h - some file

/// Valid Request Flags
typedef enum _REQUEST_FLAGS
{
    /// ONE
    FIRST   = 0x01,  
    /// TWO
    SECOND   = 0x02,  
    /// Some BIT
    SomeBit  = 0x10,
    /// Another BIT
    AnotherBit  = 0x40
} RequestFlags;

See attached zip

Version
1.8.20 Win10 64bit
(binary distribution)

Stack trace
not a crash

Additional context
n/a

Doxyfile.zip

[albert-github]

There is no flag to set the possibility to have the values of the enum in the detailed description, so this will be an enhancement.

Note: not all enum values have an explicit assigned value, will be hard / not possible for doxygen to figure out what these values should be (especially in case there is a mix of values and mnemonics in the assigned values, doxygen is not a compiler)

[bitblitz]

Thanks for the reply. I don't think it's necessary for doxygen to figure out automatic values for this to be useful. When specific values are given - especially in the fairly common "flag" use case, the values make the detailed table much more useful. Thanks for considering the enhancement.

[albert-github]

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

[bitblitz]

@albert-github Anything I can do to help move this pull request along?

[albert-github]

No there is nothing you can do, it is up to @doxygen to decide whether or not this proposed pull request should be integrated or not. You already stated the importance to you by means of your comment.

[doxygen]

@bitblitz Why are the actual numerical values important in the documentation? I would expect you define the enumeration values in order for the user not to have to worry about the exact values anymore. So in which situation is this useful information?

[bitblitz]

@doxygen
The exact values are necessary any time you are are building a binary-layer interface. This happens frequently with embedded systems and drivers. For example, the caller might be written by Team A , while the callee might be implemented by Team B with separate source in an entirely different language. Team A may want to use an enum in their code to make their own code clear, but they need to communicate the actual binary values to Team B because they are not sharing source.
In that case, clear, easy to use documentation is important for cross-team communication. The Doxygen output is far more useful for this kind of cross-team communication with this change.

[davebytes]

I'd like to jump in here, I would love to see this feature as well. It makes it so users can look to the doc for enum values, rather than having to go header diving. This is good for finding hex error codes, specialized masks/bitfields, etc.

[sternmull]

I also often find myself in situations where I look up the documentation for an enum in Doxygen. References link to the table that contains just the identifier and its documentation. An example where the values are needed is when you have to know the value when passing such an enum from a dynamic language (such as calling a COM interface from Python via dynamic bindings).
So I often wished what this request is asking for: An additional column in the Table that repeats the values in the same way as they are already shown in the "enum { ... }" section of the output. Alternatively: Get rid of the table, link to the enum section and pot the documentation there.
For now you have to be an experienced Doxygen-consumer to know that you can find the values at the other place of the HTML page.

[snellejelle99]

@doxygen
Is there any progress on this issue?

For my use case:
We are sending enum values from our embedded device to an MQTT broker.
A different team is going to make a front end using this data and they want to know what these "arbitrary" numbers mean.
Including the actual numerical value in the documentation would simplify our workflow. Right now we manually include the numerical value in the doxygen inline comments for every enum value.