Doxygen对声明或定义发表评论？ [英] Doxygen comments on declarations or on definitions?

问题描述

刚刚开始使用Doxygen在这里记录我的代码，不能决定把它们放在哪里。

Just started using Doxygen for documenting my code here and can't decide where to put them.

看起来好像把它们放在声明文件中，因为它实际上声明了你收到什么，你要返回什么， ，除了那些只在声明文件中的数据成员显然只能记录在那里。

At first look it seems better to put them in the declaration files as it is there where you actually declare what you receive, what you are going to return and stuff like that, apart from that things like data members that are only in the declaration files can obviously only documented there.

但是我常常在实现文件中找到更方便的注释方法对我来说更容易访问，声明文件不会混乱与几十行的评论，使得更难找到你在开发时寻找。

But often I find handier to comment methods in the implementation files as they are more accessible to me and the declaration file doesn't get cluttered with dozens of lines of comments making it harder to find what you look for when developing.

经验？

推荐答案

TL; DR：带声明​​的评论

<我有两种风格的经验。还有第三个文档被拆分：@brief和@param在标题和所有其余的源文件，非常奇怪。目前，我更喜欢把所有Doxygen评论与声明，并认为我会坚持这种偏好。我继续找到更多的理由继续这样做。

TL;DR: Comments with declaration.

I have experience with both styles. Also a third where the documentation was split: @brief and @param in the header and all the rest in the source file, very bizarre. Currently, I prefer to put all Doxygen comments with the declaration and think I'll stick with that preference. I keep finding more reasons to keep doing it this way.

Doxygen声明喜欢的库的用户。其中Doxygen的定义喜欢维护者/增强。根据我的经验，图书馆的用户比维护者多得多。

Doxygen with the declaration favors users of the library. Where Doxygen with the definition favors maintainers/enhancements. In my experience there are far more users of a library than there are maintainers.

我总是将我的代码视为其他用户的库。一年后从现在你的古老格言将是另一个用户是非常真实的。虽然我写的类，我需要快速引用一个类的接口，它的定义是足够好。在这种情况下，标题中的Doxygen注释只是分心。然而，普通用户发现声明不足以回答他们的问题。因此，他们必须找到定义，以获得其余的意见。

I always treat my code as a library for other users. The old adage that a year from now you will be the other user is very true. While I am writing the class and I need quick reference of a class's interface, its definition is plenty good enough. In this case the Doxygen comments in the header is just distracting. However, regular users find the declarations to be insufficient to answer their questions. So they'll have to find the definitions as well to get at the rest of the comments.

这篇关于Doxygen对声明或定义发表评论？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！