c++ - Is there a way to check the doxygen comment is the same for the declaration and the definition? - Stack Overflow

admin管理员组

文章数量:1303269

In my team we have a design-by-contract approach to our C++ code, which we express through our Doxygen comments.

We write a Doxygen comment at the top of each function declaration, explaining what its parameters are, its preconditions, its return values and postconditions, so that the callers know exactly how the function should behave without any need to look at the function implementation.

We also want that Doxygen comment to be at the top of each function definition, because it allows those writing or maintaining the function to known what the implementation should do, so that they can make sure it does the correct thing.

However, since the same Doxygen comment needs to be in two places, that raises the question of how to ensure both stay the same over time. Is there a tool or a Doxygen option that can be used to check that both comments are the same?

In my team we have a design-by-contract approach to our C++ code, which we express through our Doxygen comments.

We write a Doxygen comment at the top of each function declaration, explaining what its parameters are, its preconditions, its return values and postconditions, so that the callers know exactly how the function should behave without any need to look at the function implementation.

We also want that Doxygen comment to be at the top of each function definition, because it allows those writing or maintaining the function to known what the implementation should do, so that they can make sure it does the correct thing.

However, since the same Doxygen comment needs to be in two places, that raises the question of how to ensure both stay the same over time. Is there a tool or a Doxygen option that can be used to check that both comments are the same?

• c++
• doxygen

Share Improve this question Follow asked Feb 10 at 11:05 EternalEternal 2,95922 gold badges1717 silver badges2626 bronze badges 16

• 2 I'm sorry, but I can't see how duplicating comments is the best solution to "I need to read the comment while implementing" problem. Assuming the information you need is not already shown by IDE on hover, you can simply open second tab/window to view it. – Yksisarvinen Commented Feb 10 at 11:16
• 2 Do I understand it correctly, you want to have the same comment at 2 places? If so this is indeed screaming for problems (documentation not correct anymore). There is no doxygen option for this. – albert Commented Feb 10 at 11:44
• 4 Only document the declarations. – Eljay Commented Feb 10 at 12:01
• 2 Relying on comments (as contract managment) is a waste of time, duplicated or not. What you need is a single source of truth (code!_. Let an architect/tech lead create a repository with only declarations and unit tests (that represent/validate the contracts). Then create another repo were developers can develop implementations that should meet the unit tests. – Pepijn Kramer Commented Feb 10 at 13:38
• 1 @ÖöTiib Are you saying you do that yourself? Do you not have something that compiles the code and runs unit tests automatically before code review? – Eternal Commented Feb 10 at 13:38

 |  Show 11 more comments

1 Answer 1

Sorted by: Reset to default 2

Doxygen does not have an option to check that both comments are the same. It was not designed for this scenario.

In fact, this double-documenting runs counter to the first entry in Doxygen's list of features, which is "Requires very little overhead from the writer of the documentation." The point of generating documentation is so that there can be a single source of truth from which all other documentation is generated, removing the need to document in more than one place. Providing two sources of truth runs counter to this goal.

For similar reasons, it seems doubtful that there would be another tool designed to detect Doxygen comments going out of sync, but maybe there is one not tailored specifically to Doxygen (one that just verifies that declaration and definition have the same comment)? I will leave it to others to find such a tool, if it exists. For now, your best bet may be either to change your convention about double-documenting or to hack the Doxygen source code.

(If your convention could be changed, perhaps a good convention would be to document a definition with a link to a web page generated by Doxygen from the declaration? Just a thought. You know your circumstances better than me.)

本文标签：