documentation - 在Doxygen中的注意，注释，备注，待办事项和警告之间进行选择

Question

文档生成器Doxygen允许将注释标记为关注，注释，备注，待办事项或警告。

我应该遵循什么准则来将评论正确地分类为其中之一？

Answer 1

与未标记的其他部分相比，所有这些标记均用于突出显示文档中特别值得注意的部分。它们全都用来引起读者对标记段落的关注。

注意是最通用的标记，在大多数情况下您希望读者“注意”本节中描述的问题时，使用该标记。

注意标签可用于突出显示特别重要的注释，您不想让读者忽略它。

如果读者在使用记录的物品时不小心，可能会产生负面影响，则应使用警告标签代替注意标签。

“备注”和“备注”标签可用于重要性较低的笔记。如果您想以“哦，顺便说一句”的方式描述事物，则Remark标记对此很有用。

Todo标签的使用方式与您列出的其他方式不同。通常用于指示注释中描述的代码具有一个或多个未完成的方面。这会同时向代码用户和代码编写者发出警告，即在相关代码的更高版本中需要解决某个功能或错误。 Doxygen具有一项很酷的功能，它将在生成的输出中的自己部分中列出所有待办事项。可以通过编辑Doxyfile并将行GENERATE_TODOLIST = YES更改为GENERATE_TODOLIST = NO来关闭它。

与Todo标记相关的是Bug标记，可以专门用于标记描述软件错误的文档。同样，Doxyfile的GENERATE_BUGLIST = YES行会导致所有Bug都列在其各自的部分中。可以使用GENERATE_BUGLIST = NO将其关闭。