doxygen:multiple comments - chunhualiao/public-docs GitHub Wiki

for doxygen, if a function has comments in two places: 1) right before the function prototype header file, and 2) in a separated .dox file with @fn linked to the function. Both files are scanned by doxygen. which comment will doxygen pick to generate html reference pages? why?

In Doxygen, if a function has comments in two places—one directly before the function prototype in a header file and another in a separate .dox file using the @fn command—Doxygen will typically prioritize the comments that are directly associated with the function prototype in the header file.

Reasons:

  1. Proximity: Doxygen tends to favor comments that are immediately adjacent to the code they describe. This is because they provide context and clarity about the specific implementation.

  2. Clarity and Maintenance: Comments in the header file are usually more straightforward to maintain and update alongside the code. This makes it easier for developers to ensure that the documentation stays in sync with the implementation.

  3. Configuration Settings: Depending on the Doxygen configuration settings (like EXTRACT_ALL, EXTRACT_PRIVATE, etc.), the behavior might vary slightly, but generally, comments in the header file take precedence.

Conclusion:

If both comments are valid and scanned by Doxygen, the comment directly preceding the function prototype in the header file will be used for generating the HTML reference pages. If you want to ensure that the comments in the .dox file are also considered, you might need to explicitly reference them or ensure they are integrated properly in your documentation strategy.

However, it's important to note that Doxygen may merge documentation from multiple sources in some cases3. If there are unique details in the .dox file that don't conflict with the header comments, Doxygen might include both. But in case of conflicts, the header file comments will typically take precedence.

To avoid confusion and maintain consistency, it's recommended to document each entity in only one place, preferably near its declaration or definition in the source code35.