如何在 ANSI C 中编写文档注释？ [关闭]答案

【问题标题】：How to write documentation comments in ANSI C? [closed]如何在 ANSI C 中编写文档注释？ [关闭]
【发布时间】：2012-02-11 23:31:52
【问题描述】：

我找不到如何用 C 编写 cmets。我的意思是我知道 // 和 /* */，我的意思是我在哪里可以找到好的做法？如果我有一个函数，我该如何写@param variable is the value bla bla，就像用Java一样？

这有什么标准吗？或者我可以像在 Java 中那样做吗？

【问题讨论】：

实际上，您甚至不能在 ANSI C 中使用 //。只有从 C99 开始，它们才允许使用 //。（虽然 GCC 允许它作为扩展。）
C 中仅支持 /* */。// 是 C++ 中的新增项
术语“ANSI C”通常指的是 1989 年 ANSI 标准所描述的语言，但严格来说这是不正确的。 1990 年，ISO 发布了相同的标准（有一些新的介绍材料和重新编号的部分），ANSI 采用了它。 1999 年，ISO 发布了新的 C 标准，ANSI 也采用了它，使 1989/1990 标准正式过时。 2011 年底，ISO 发布了另一个新的 C 标准，ANSI 也采用了该标准。除了第一个，C 标准最初是由 ISO 发布的，而不是 ANSI——最好按年份参考标准。
唉，仍然有编译器甚至不支持 1999 ISO C 标准。对 1990 年标准的支持几乎是普遍的。
@KeithThompson 非常正确 - 编译器仍然没有实现 C++89 - 我不知道 C 也会进行改造 - 我一直专注于 C++0x（或 C+ +11，现在已知）。似乎变化很小 - 真是浪费时间。

标签： c documentation code-documentation

【解决方案1】：

有很多不同的标准，如果你想生成文档，试试doxygen

【讨论】：

【解决方案2】：

您可以使用javadoc标准，然后使用理解javadoc的doxygen生成文档。

在 doxygen 中，我建议使用选项 JAVADOC_AUTOBRIEF 设置为 YES。如果 JAVADOC_AUTOBRIEF 标记设置为 YES，则 doxygen 会将 Javadoc 样式注释的第一行（直到第一个点）解释为简要说明。

类定义示例：

/**
 * A brief description. A more elaborate class description
 * @param bool somebool a boolean argument.
 * @see Test()
 * @return The test results
 */

（更多示例in the doxygen manual）

安装非常简单，有一个 GUI 和一个漂亮的图形可视化可用：

apt-get install doxygen doxygen-gui graphviz

运行调用doxywizard的gui并使用向导设置，只有JAVADOC_AUTOBRIEF必须在“专家”设置中设置。

【讨论】：

一个很好的答案，举个例子。

【解决方案3】：

没有遵循贵公司规定的标准的标准。
从项目创建文档的一种流行方法是使用 doxygen。

【讨论】：

【解决方案4】：

一种选择是使用编写 cmets 的 doxygen 格式 - 这具有能够为您的代码生成 html/latex 和其他类型的文档的额外好处。

【讨论】：