"WARNING: Duplicate declaration" for header file declaration and .c implementation

[CareF]

I think it's probably I am not using it correctly, but I am trying to use breathe for a small C module in a Python project. In the C code I have a function declared in a header file and implemented in a .c file. Example:

/**
 * \file
 *
 * \brief foo header file
 */
#ifndef FOO_H_
#define FOO_H_

void foo();

#endif 

/**
 * \file
 *
 * \brief foo source code
 */

#include "foo.h"
/**
 * foo func implementation
 */
void foo()
{
    ;  
}

I believe it's a very common way of arranging C code, but when I do this with doxygen+breathe, I got warning WARNING: Duplicate declaration, and also at first error but fixed I believe #394 with git version of sphinx. I also saw sphinx-doc/sphinx#4820 but it looks like a different case.

I think it's that doxygen creates symbol for the foo in both header file and .c file. So what should be the practice for such use case?

Thank you!

[vermeeren]

I believe the function contract is usually documented in the header file, though this should not matter. If I remember correctly this warning is caused when you list the same "doxygen object" in the RST multiple times. For example in both a.rst and b.rst you have .. doxygenfunction:: foo.

Also see #321, #378 and Sphinx upstream sphinx-doc/sphinx#4981. Does this help or am I missing something still?

[CareF]

@melvinvermeeren Thank you for the reply. But the only thing I use for now about doxygen object is .. doxygenindex::. See attached smallest example if it helps.
eg.zip

[t-b]

On my projects I have a huge number of Duplicate declaration warnings. You also get them if you do make in the breathe project.

[vermeeren]

@CareF the attached example renders to the following:

The documentation for void foo() is included twice, once through the header file and once through the source file. This is the reason for the Duplicate declaration. The fix is to structure your project in such a way that things are listed only once. Typically only the APIs are documented, meaning header files only. Though there are many other ways to do things.

[CareF]

@melvinvermeeren Thank you for the advice!
That would mean that I should only include head file in doxygen. But when I want a document of APIs for users as well as what's inside for future developers, which means I would want documentation in both header files and implementation, is there anything I can do?

[vermeeren]

What I would do is document the "usage of the API" in the proper docs, through doxygen/sphinx, and document internal notes, for the implementation but not the function contract, as regular comments inside the source files itself since anyone editing the source will see them inside the .c anyway.

As a bonus this structure will help keep the main generated docs clean with just the public API and function contracts, the rationale for implementation decisions stays next to the implementation itself.

(For bigger software I find it useful to have both a public API, which is documented, and an internal API, which is also documented. This is useful for when you have standalone-ish subsystems in the software, which do have function contracts but are not available to whoever is using the library itself. I believe this is not needed in your case.)

[CareF]

Thank you @melvinvermeeren !
I am trying to add \cond comments in c files to avoid duplicate, and then I realize that if I want to use breathe-apidoc to generate lists of files, it gives me toc of files as well as struct, which seems unavoidably duplication: A struct will always show once in the file page containing it and in its struct page. I assume that's something sphinx fundamentally cannot handle, though.

[vermeeren]

There are some workarounds by passing the -g option to breathe-apidoc as well as some other hacking/patching you could do, but until upstream implements aliases for declarations the options that won't result in warnings are rather limited.

[jakobandersen]

As @melvinvermeeren mentions there are some basic problems with index-like lists which triggers the warnings, which will be fixed when the alias support is implemented in Sphinx and Breathe uses it. Note that this problem has always been there, but the explicit warnings are relatively new.
However, from your screen shot it looks like there really are two documentation entries for foo which is not supported in Sphinx. You are most welcome to open an issue in Sphinx if you believe some feature is missing. It would be great if you can then provide a sketch of how you would expect the documentation to look.

[krzychb]

Hi all,

I have noticed this issue after upgrade:

• Sphinx 1.6.5 -> 1.8.4
• Breathe 4.7.3 -> 4.11.1

Personally I like no explicit warnings as it was before. On the index, for each duplicate documentation entry there is a reference in square brackets [1], [2], etc., see below how it looks like for functions ulp_load_binary() or ulp_run().

I am happy with this method of handling duplicates on the index. I am not sure if this is the same as "index-like lists" mentioned by @jakobandersen above or there are some other issues elsewhere.

We need duplicate documentation entries for user convenience to document old (Make) and new (CMake) build systems. The workflows for each system is different and before deprecation of the old build system we need to maintain documentation for both.

@CareF thank you for documenting this issue and I am happy to see some discussion going on already! My nightmare is an old issue entered months or years ago with nobody interested in resolution but me :)

[vermeeren]

I guess the main purpose of this issue has been achieved earlier. Improvements will happen eventually through other issues. Closing for now.