cli*_*ith 6 c++ documentation doxygen commenting
我正在编写一个C++静态库,我一直在实现文件中使用doxygen注释进行评论.我从来没有真正关心文档,但我正在研究一些现在需要为用户做好记录的事情,而且我正在尝试替换我以前想要编码的坏习惯,而不是用更好的软件工程文档实践.
无论如何,前几天我意识到我需要一些不同类型的文档,一种类型的库用户(doxygen手册),然后评论我自己或未来的维护者,更多地处理实现细节.
我的解决方案之一是将文件,类和方法的doxygen注释放在实现文件的底部.在那里,它们将被排除在外,我可以在方法定义中/周围包含正常注释,以使程序员受益.我知道这是更多的工作,但它似乎是我实现两种不同类型的评论/文档的最佳方式.您是否同意或有任何可能有用的解决方案/原则.我浏览了网站,但无法找到任何处理此问题的线程.
另外,我真的不想在评论中丢失接口文件,因为我觉得最好让界面说明一切.如果用户需要更深入地了解库接口,我宁愿手册成为用户可以查看的地方.我在这里走在正确的轨道上吗？
任何想法或评论都非常感谢.
编辑:感谢大家的意见.我从听到他们那里学到了很多东西.我想我更好地理解如何将用户手册与对维护者有用的代码注释分开.我喜欢@jalf有关于"散文"风格手册的想法,该手册有助于解释如何使用该库.我真的认为这比参考手册更好.话虽如此......我也觉得参考手册可能真的派上用场了.我想我会将他的建议与其他人的想法结合起来并尝试创建一个混合体.(散文手册(使用doxygen标签,如页面,部分,小节)链接到参考手册.)我喜欢@jalf的另一个建议是没有整个手册插入其中的代码的想法.我可以通过将所有doxygen注释放在实现文件的底部来避免这种情况.这使得头文件清晰,实现干净,以便对维护实现的人发表有用的注释.我们将看看这是否真的有效.这些只是我对迄今学到的知识的看法.我不是肯定的,我的方法可以很好地运作,甚至可以实用.只有时间会给出答案.
我一般认为用户的评论不应该在代码中内联,如doxygen评论或类似的东西.它应该是散文形式的单独文件.作为库的用户,我不需要或不想知道函数的每个参数的含义.希望,这是显而易见的.我需要知道这个功能是做什么的.而且我需要知道为什么会这样做以及何时调用它.我需要知道适用的前后条件.当我调用它时,函数做了什么假设,它返回时提供了什么保证？
图书馆用户不需要评论,他们需要文档.描述库的结构以及它是如何工作以及如何使用它,这样做外的代码,实际文本文件内.
当然,代码仍可能含有冲着维护者的意见,解释了为什么执行的样子是这样,或者它是如何工作的,如果不是很明显.但是库用户需要的文档不应该在代码中.