在哪里放置一个内部库的doxygen注释块 - 在H或CPP文件？ [英] Where to put the doxygen comment blocks for an internal library - in H or in CPP files?

问题描述

常识告诉Doxygen注释块必须放在类，结构，枚举，函数，声明所在的头文件中。我同意这是一个声音的参数，一个库的意思是分布没有它的源（只有头和库与目标代码）。

The common sense tells that the Doxygen comment blocks have to be put in the header files where the classes, structs, enums, functions, declarations are. I agree that this is a sound argument for a libraries that are mean to be distributed without its source (only headers and libs with object code).

BUT ... I当我开发公司内部（或作为自己的一个侧面项目）库时，我们一直在考虑完全相反的方法，它将与其完整的源代码一起使用。我建议的是把大的注释块放在实现文件（HPP，INL，CPP等）中，以便不要混淆在头中声明的类和函数的界面。

BUT...I've been thinking of the exact opposite approach when I'm developing an internal to the company (or as a side project for myself) library that will be used with its full source code. What I propose is to put the large comment blocks in the implementations files (HPP, INL, CPP, etc) in order NOT to clutter the inteface of the classes and functions declared in the header.

优点：

• 在头文件中更少杂乱，


• 使用Intellisense时预览的注释块不会冲突 - 这是我在对某个函数的注释块中观察到的缺陷。 H文件，并将其内联定义放在同一个.H文件中，但包含在.INL文件中。

strong>

Cons:

• （显而易见的）注释块不在声明所在的头文件中。

那么，你认为和可能会有什么建议？

So, what do you think and possibly suggest?

推荐答案

类注释放在类前面，方法注释放在方法前面。

Class comments go in front of classes, method comments in front of methods.

这是确保事物得以维护的最佳方法。它还保持您的头文件相对精简，避免触摸人的更新方法docs的问题，导致头变脏，并触发重建。我实际上已经知道人们使用它作为撰写文档的借口！

That is the best way to make sure things are maintained. It also keeps your header files relatively lean and avoids the touching issue of people updating method docs causing headers to be dirty and triggering rebuilds. I have actually known people use that as an excuse for writing documentation later!

这篇关于在哪里放置一个内部库的doxygen注释块 - 在H或CPP文件？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！