我正在编写一个C++静态库,我一直在实现文件中使用doxygen注释进行评论.我从来没有真正关心文档,但我正在研究一些现在需要为用户做好记录的事情,而且我正在尝试替换我以前想要编码的坏习惯,而不是用更好的软件工程文档实践.
无论如何,前几天我意识到我需要一些不同类型的文档,一种类型的库用户(doxygen手册),然后评论我自己或未来的维护者,更多地处理实现细节.
我的解决方案之一是将文件,类和方法的doxygen注释放在实现文件的底部.在那里,它们将被排除在外,我可以在方法定义中/周围包含正常注释,以使程序员受益.我知道这是更多的工作,但它似乎是我实现两种不同类型的评论/文档的最佳方式.您是否同意或有任何可能有用的解决方案/原则.我浏览了网站,但无法找到任何处理此问题的线程.
另外,我真的不想在评论中丢失接口文件,因为我觉得最好让界面说明一切.如果用户需要更深入地了解库接口,我宁愿手册成为用户可以查看的地方.我在这里走在正确的轨道上吗？
任何想法或评论都非常感谢.
编辑:感谢大家的意见.我从听到他们那里学到了很多东西.我想我更好地理解如何将用户手册与对维护者有用的代码注释分开.我喜欢@jalf有关于"散文"风格手册的想法,该手册有助于解释如何使用该库.我真的认为这比参考手册更好.话虽如此......我也觉得参考手册可能真的派上用场了.我想我会将他的建议与其他人的想法结合起来并尝试创建一个混合体.(散文手册(使用doxygen标签,如页面,部分,小节)链接到参考手册.)我喜欢@jalf的另一个建议是没有整个手册插入其中的代码的想法.我可以通过将所有doxygen注释放在实现文件的底部来避免这种情况.这使得头文件清晰,实现干净,以便对维护实现的人发表有用的注释.我们将看看这是否真的有效.这些只是我对迄今学到的知识的看法.我不是肯定的,我的方法可以很好地运作,甚至可以实用.只有时间会给出答案.
我有一个用MinGW构建的静态库,我试图从Qt应用程序链接到该库.我不断收到由库中的一个目标文件引起的链接器错误.这个文件实际上声明了几个Boost头文件,一个用于使用shared_ptr,另一个用于使我可以使类不可复制.我相信使用这个提升功能是导致问题的原因,但我不知道为什么.如果我在Qt应用程序中注释掉使用文件中定义的类的类,那么Qt应用程序链接正常.这是输出的错误部分:
C:\ blah\build\windows\mingw\libfoo.a(foo_ctis.cpp.obj):foo_ctis.cpp :(.text + 0x10a):未定义引用`__gxx_personality_sj0'
C:\ blah\build\windows\mingw\libfoo.a(foo_ctis.cpp.obj):foo_ctis.cpp :(.text + 0x12f):未定义引用`_Unwind_SjLj_Register'
C:\ blah\build\windows\mingw\libfoo.a(foo_ctis.cpp.obj):foo_ctis.cpp :(.text + 0x203):未定义引用`_Unwind_SjLj_Resume'
C:\ blah\build\windows\mingw\libfoo.a(foo_ctis.cpp.obj):foo_ctis.cpp :(.text + 0x20e):未定义引用`_Unwind_SjLj_Unregister'
C:\ blah\build\windows\mingw\libfoo.a(foo_ctis.cpp.obj):foo_ctis.cpp :(.text + 0x226):未定义引用`__gxx_personality_sj0'
C:\ blah\build\windows\mingw\libfoo.a(foo_ctis.cpp.obj):foo_ctis.cpp :(.text + 0x24b):未定义引用`_Unwind_SjLj_Register'
C:\ blah\build\windows\mingw\libfoo.a(foo_ctis.cpp.obj):foo_ctis.cpp :(.text + 0x31f):未定义引用`_Unwind_SjLj_Resume'
C:\ blah\build\windows\mingw\libfoo.a(foo_ctis.cpp.obj):foo_ctis.cpp :(.text + 0x32a):未定义引用`_Unwind_SjLj_Unregister'
C:\等等\建立\ WINDOWS\MinGW的\ libfoo.a(foo_ctis.cpp.obj):foo_ctis.cpp :(文字$ _ZN5boost6detail12shared_countC1IN3foo25foo_SomeClassImplEEEPT_ [升压::详细:: SHARED_COUNT :: SHARED_COUNT(富:: foo_SomeClassImpl*)] + 0xc):未定义对`__gxx_personality_sj0'的引用
C:\等等\建立\ WINDOWS\MinGW的\ libfoo.a(foo_ctis.cpp.obj):foo_ctis.cpp :(文字$ _ZN5boost6detail12shared_countC1IN3foo25foo_SomeClassImplEEEPT_ [升压::详细:: SHARED_COUNT :: SHARED_COUNT(富:: foo_SomeClassImpl*)] + 0x31):对`_Unwind_SjLj_Register'的未定义引用
C:\等等\建立\ WINDOWS\MinGW的\ libfoo.a(foo_ctis.cpp.obj):foo_ctis.cpp :(文字$ _ZN5boost6detail12shared_countC1IN3foo25foo_SomeClassImplEEEPT_ [升压::详细:: SHARED_COUNT :: SHARED_COUNT(富:: foo_SomeClassImpl*)] + 0xfb):对`_Unwind_SjLj_Resume'的未定义引用
C:\等等\建立\ WINDOWS\MinGW的\ libfoo.a(foo_ctis.cpp.obj):foo_ctis.cpp …
我有一个用 C++ 构建的静态库。我把它分成了许多头文件和源文件。我想知道将库的客户端可能需要的所有头文件包含在一个头文件中是否更好，而这些头文件又可以包含在他们的源代码中，还是只包含他们需要的头文件？这会导致代码不必要的臃肿吗？我不确定未被使用的类或函数是否仍会被编译到他们的产品中。
谢谢你的帮助。
我已经设置SOURCE_BROWSER = NO，VERBATIM_HEADERS = YES因为我希望客户能够看到头文件。但是，我只想让他们看到某些标题。如何做到这一点的最佳方法。
在此先感谢您的帮助！
编辑：这似乎有效，但我会对任何其他更好的方法感兴趣。
EXCLUDE_PATTERNS = */.svn/* *debug* *impl* *boost*
我正在使用doxygen生成我的代码文档的PDF.PDF在使用时有很大的余量PAPER_TYPE = letter.它在使用时看起来不错,a4wide但我想对它有更多的控制权.我想使用一个名为geometry的包,但无法弄清楚在哪里添加代码如下:
\usepackage[top=2.9cm,left=2in,bottom=1in,right=1in]{geometry}
如果可能的话,我不想更改doxygen生成的tex文件.
我希望能够在主进程中使用CreateProcess打开GUI应用程序,并在我在主进程中创建的窗口中显示GUI.有谁知道如何实现这一目标？谢谢!