在 Doxygen 中选择注意、注释、评论、待办事项和警告
Choosing between attention, note, remark, todo and warning in Doxygen
文档生成器 Doxygen 允许将一条评论标记为 attention、note、remark、todo 或 warning.
我应该遵循哪些准则才能将评论正确归类为其中之一？
所有这些标签都用于突出文档的某个部分，与其他没有这样标记的部分相比，特别值得注意。它们都用于吸引 reader 对标记段落的注意。
Note 是最通用的标签，在大多数情况下您需要使用 reader 到 "take notice" 的标签节中描述。
Attention 标签可用于突出显示您不希望 reader 忽略的特别重要的注释。
如果 reader 不小心使用正在使用的项目可能会产生负面后果，则应使用 Warning 标签而不是 Attention记录在案。
Remark 和 Remarks 标签可用于不太重要的注释。如果您想以 "oh, by the way" 的方式描述某些内容，Remark 标签对此很有用。
Todo 标签的使用方式与您列出的其他标签不同。它通常用于表示注释中描述的代码有一个或多个未完成的方面。这提醒代码用户和代码编写者需要在相关代码部分的以后修订中解决功能或错误。 Doxygen 有一个很酷的功能，它会在生成的输出中将所有 Todo 一起列在它们自己的部分中。这可以通过编辑 Doxyfile 并将行 GENERATE_TODOLIST = YES 更改为 GENERATE_TODOLIST = NO 来关闭。
与 Todo 标签相关的是 Bug 标签，它可以专门用于标记描述软件错误的文档。同样，Doxyfile 有一个 GENERATE_BUGLIST = YES 行，导致所有 Bug 都列在它们自己的部分中；这可以用 GENERATE_BUGLIST = NO.
关闭
文档生成器 Doxygen 允许将一条评论标记为 attention、note、remark、todo 或 warning.
我应该遵循哪些准则才能将评论正确归类为其中之一？
所有这些标签都用于突出文档的某个部分，与其他没有这样标记的部分相比，特别值得注意。它们都用于吸引 reader 对标记段落的注意。
Note 是最通用的标签，在大多数情况下您需要使用 reader 到 "take notice" 的标签节中描述。
Attention 标签可用于突出显示您不希望 reader 忽略的特别重要的注释。
如果 reader 不小心使用正在使用的项目可能会产生负面后果，则应使用 Warning 标签而不是 Attention记录在案。
Remark 和 Remarks 标签可用于不太重要的注释。如果您想以 "oh, by the way" 的方式描述某些内容，Remark 标签对此很有用。
Todo 标签的使用方式与您列出的其他标签不同。它通常用于表示注释中描述的代码有一个或多个未完成的方面。这提醒代码用户和代码编写者需要在相关代码部分的以后修订中解决功能或错误。 Doxygen 有一个很酷的功能，它会在生成的输出中将所有 Todo 一起列在它们自己的部分中。这可以通过编辑 Doxyfile 并将行 GENERATE_TODOLIST = YES 更改为 GENERATE_TODOLIST = NO 来关闭。
与 Todo 标签相关的是 Bug 标签，它可以专门用于标记描述软件错误的文档。同样，Doxyfile 有一个 GENERATE_BUGLIST = YES 行，导致所有 Bug 都列在它们自己的部分中；这可以用 GENERATE_BUGLIST = NO.