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

Question

文档生成器 Doxygen 允许将一条评论标记为 attention、note、remark、todo或警告。

我应该遵循哪些准则才能将评论正确归类为其中之一？

Answer 1

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

Note 是最通用的标签，在您希望读者“注意”本节所述内容的大多数情况下使用。

注意标签可以用来突出一个特别重要的注释，一个你不希望读者忽略的注释。

如果读者不小心使用所记录的项目，可能会产生负面后果，则应使用 Warning 标签而不是 Attention。

Remark 和 Remarks 标签可用于不太重要的注释。如果您想以“哦，顺便说一下”的意思来描述某事，Remark 标记对此很有用。

Todo 标记的使用方式与您列出的其他标记不同。它通常用于表示注释中描述的代码有一个或多个未完成的方面。这会提醒代码用户和代码编写者，某个功能或错误需要在相关代码部分的后续版本中解决。 Doxygen 有一个很酷的功能，它会在生成的输出中将所有 Todos 一起列出在它们自己的部分中。这可以通过编辑 Doxyfile 并将行 GENERATE_TODOLIST = YES 更改为 GENERATE_TODOLIST = NO 来关闭。

与 Todo 标签相关的是 Bug 标签，它可以专门用于标记描述软件错误的文档。同样，Doxyfile 有一个GENERATE_BUGLIST = YES 行，它会导致所有错误都列在它们自己的部分中；这可以通过GENERATE_BUGLIST = NO 关闭。