Warning: Duplicate target detected: struct

[AngusWooster]

We use shpinx with breath to document our c projects.
In the .rst , I use doxygenstruct to display the same struct documentation in different section.

I got many warning message shown as below.
WARNING: Duplicate ID: "structsec__pal__fun"
WARNING: Duplicate explicit target name: "structsec__pal__fun".

Have any methods to avoid showing those duplicate warning message?

[jakobandersen]

Each entity may only be declared once, such that there is one place where all links to it can go.
Depending on your use-case for the alternate location it may be enough to just link back to the primary location with a :c:struct: role. If you want to show struct members as well I suggest the c:alias directive (https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-c-alias).

[AngusWooster]

Hi
Thanks for giving the information about :c:struct:
It seems to documentation of C API instead of showing comment.

In my case, I want to show the comment of each struct members in different section, so I use doxygenstruct to display them.
Have any idea to avoid WARNING: Duplicate message?

[vermeeren]

@AngusWooster Can you try using the :no-link: option on all except one of the directives. https://breathe.readthedocs.io/en/latest/directives.html The one directive without the option will become the main declaration which links will point to.

I recall something something fairly recent with potential trouble (or perhaps just hackyness) related to the option. #356 may also be relevant. Still it's worth a try, might be just what you need in this specific case.

It might also be useful to check other issues related to this, which are quite a lot: https://github.com/michaeljones/breathe/issues?q=is%3Aissue+duplicate

[AngusWooster]

Hi
Thanks for giving me this information.
It can fix some issues.
It eliminates WARNING: Duplicate ID: "structsec__pal__fun". and WARNING: Duplicate explicit target name: "structsec__pal__fun".

But it still show WARNING: Duplicate C++ declaration. .... Declaration is '.. cpp:struct:: sec_pal_fun'.
In my document, I use .. doxygenstruct:: to point a same struct name.

They look like below in .rst file:

.. doxygenstruct:: sec_pal_fun
:project: TEST
:members: pal_sec_init
:no-link:

.. doxygenstruct:: sec_pal_fun
:project: TEST
:members: pal_sec_exit
:no-link:

Have any ideas can link to back to a same .. doxygenstruct:: , but you can get information about the different struct members in different section?

[vermeeren]

@AngusWooster Unfortunately I don't know of a further solution, it has been some time since many improvements were made with the duplicate declarations but it still is not perfect. Ideally each directive on a specific target is only used once.

For a practical workaround I can only suggest using some grep -v '^WARNING: Duplicate' kind of thing in your make doc pipeline, so it filters out these kind of warnings.

Have any ideas can link to back to a same .. doxygenstruct:: , but you can get information about the different struct members in different section?

Not entirely sure what you mean here, can you explain?

[jakobandersen]

As mentioned previously, there can be only one declaration of any entity, e.g., of sec_pal_fun. So you may/should only have one instance of .. doxygenstruct:: sec_pal_fun, which Breathe translates to .. c:struct:: sec_pal_fun or .. cpp:struct:: sec_pal_fun (plus content) depending on the language configuration.
The no-link option is translated to the noindex option in Sphinx (see the first paragraph of https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#basic-markup). However, for both C and C++, this option previously did nothing, and has now been removed (sphinx-doc/sphinx#7895). I'm not sure if there is a warning from Sphinx about it with the way Breathe invokes directives. Perhaps Breathe should give a warning.
Currently there is no pretty way to duplicate the struct in this way without icky side effects. My suggestion from earlier with the alias would something like the following:

.. doxygenstruct:: sec_pal_fun
   :project: TEST
   :members: pal_sec_init

.. cpp:alias:: sec_pal_fun

The second will then insert a link to the declaration of sec_pal_fun. In the future the cpp:alias will also support a maxdepth option to insert links to nested declarations similar to the C-version.
If you can elaborate a bit on the context, on what you would like to achieve, perhaps there is a better solution.

(with a bit of haxing with .. cpp:namespace directives it would be possible to declare the struct twice, but then the names would be different)

[AngusWooster]

Hi
I am very very appreciated you guys getting back to me.

In my C header file, there is a C structure and its members are function pointers.
It may look like this.

/** * @brief This struct defines all security PAL interfaces */

typedef struct sec_pal_fun {
/** @name Initialization and exit*/
/**
* @brief Security functions initialization.
*
* @param[in] sdee_name indicates a unique SDEE name.
* @return SUCCESS(0) means success, others means fail.
*/
int32_t (pal_sec_init)(char sdee_name);
/
* @brief Security functions de-initialization.
*
* @return SUCCESS(0) means success, others means fail.
*/
int (*pal_sec_exit)(void);
....
...

I want to show doxygen comment of each member in sphinx different section.
It seems unable to show doxygen comment by alias, perhaps I need to amend the way of presenting.

[AngusWooster]

@AngusWooster Unfortunately I don't know of a further solution, it has been some time since many improvements were made with the duplicate declarations but it still is not perfect. Ideally each directive on a specific target is only used once.

For a practical workaround I can only suggest using some grep -v '^WARNING: Duplicate' kind of thing in your make doc pipeline, so it filters out these kind of warnings.

Have any ideas can link to back to a same .. doxygenstruct:: , but you can get information about the different struct members in different section?

Not entirely sure what you mean here, can you explain?

I am sorry, I am unfamiliar with the syntax.
Now I understand each entity can only be declared once, I was thinking that I want to show the show other doxygen comment of other members of a same c structure in different section.
Filters out Duplicate warnings, that would be a nice way for a workaround.

Thanks you : )