-
Notifications
You must be signed in to change notification settings - Fork 2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Error with unnamed structs: WARNING: Invalid definition: Expected identifier in nested name. #2683
Comments
Currently there is no way to document anonymous entities in Sphinx, and it seems that either Doxygen or Breathe invents invalid identifiers for them (to avoid collisions I guess). I would recommend the non-solution of always give entities you want to document a name. |
Thanks for the suggestion; I toyed with that solution while researching this and it definitely does work for some cases. However, there are cases where you want fully anonymous and you actually cannot name it (due to syntactic reasons); consider:
This would be and oversimplified structure describing the common parts of a device descriptor in a kernel, where depending on the hardware, it might be accessed by port (an IO port) or if mapped in memory, via a pointer to memory. For syntactical correctness, you want the right type to feed to the right access functions. For space consideration (as you might have multiple device drivers sharing this system-wide definition) you want them to share space as only one of them is going to be use at the same time. Lastly, for code cleanliness, you don't want to add another name to the union because it makes names longer (hence the unnamed anonymous union). It is a legal construct, widely used. I agree it seems counter intuitive. However, in the example given, the fields inside the union are basically considered fields of 'struct device' and the union basically is considered not to exist. The fields |
Hello Sphinx Team, I am struggling with this issue since several weeks, entered breathe-doc/breathe#346 and has been finally pointed here. Currently I am getting such warnings for two structures that contain unnamed union esp_a2d_mcc_t and esp_bt_uuid_t . There is minimum documentation site set up to demonstrate / test this issue and I am looking for any help to resolve it 😄 There are several contributors to our documentation and I would like to filter out issues with updates by failing documentation build on warnings. Obviously the fist step is to eliminate "in born" warnings. |
@eric-wieser @michaeljones @jakobandersen Any hope of handling these unnamed nested struct/union members better? We've got developers using these constructs more often across other projects and the resulting doxygen and sphinx/breathe output around these constructs is not usable. Obi-wan(s), you're our only hope. |
Anonymous entities are specified with names starting with "@", but are rendered as "[anonymous]". Fixes sphinx-doc#3593 and sphinx-doc#2683.
This should now be fixed in the master branch (to become version 1.8). Any identifier starting with |
The HCI_VS_SUBEVENT_CODE_QOS_CONN_EVENT_REPORT name was changed to HCI_VS_SUBEVENT_QOS_CONN_EVENT_REPORT. Added __PACKED_UNION=union to nrfxlib doxyfile to workaround this bug: sphinx-doc/sphinx#2683 breathe-doc/breathe#346 Ref.: DRGN-13156 DRGN-12681 Signed-off-by: Thomas Stenersen <thomas.stenersen@nordicsemi.no>
The HCI_VS_SUBEVENT_CODE_QOS_CONN_EVENT_REPORT name was changed to HCI_VS_SUBEVENT_QOS_CONN_EVENT_REPORT. Added __PACKED_UNION=union to nrfxlib doxyfile to workaround this bug: sphinx-doc/sphinx#2683 breathe-doc/breathe#346 Ref.: DRGN-13156 DRGN-12681 Signed-off-by: Thomas Stenersen <thomas.stenersen@nordicsemi.no>
The nested anonymous struct isn't properly supported in some version of breathe. sphinx-doc/sphinx#2683
Documentation can have issues with anonymous structs. sphinx-doc/sphinx#2683
Documentation can have issues with anonymous structs. sphinx-doc/sphinx#2683
Documentation can have issues with anonymous structs. sphinx-doc/sphinx#2683
Hello
The Sphinx parser, using doxygent input, seems to get confused by unnamed structures, used specially in nested unions / structs:
[from the Zephyr kernel in zephyrproject.org include/linux/i2c.h]
This will likely generate an error such as::
The simple workaround is to name that unnamed struct, with an internal name (such as __bits):
Is this a bug or there is a way to use undocumented unions / structs?
The text was updated successfully, but these errors were encountered: