如何在ANSI C中编写文档注释？

Question

我找不到如何在C语言中编写注释的方法。我的意思是，我知道关于//和/* */，但我的意思是我在哪里能找到好的实践？例如，如果我有一个函数，我该如何编写类似Java中的@param variable is the value bla bla的注释呢？

有没有任何标准可以遵循？还是我可以像在Java中那样做？

- bb2

---

实际上，在 ANSI C 中你甚至不能使用 //。只有从 C99 开始才允许使用 //。（虽然 GCC 允许使用它作为扩展功能）。 - Mysticial

C语言只支持使用 /* */ 进行注释，而 C++ 中还添加了 // 的注释方式。 - Shiplu Mokaddim

“ANSI C”一词通常指1989年ANSI标准描述的语言，但严格来说这是不正确的。1990年，ISO发布了同样的标准（其中包括一些新的导言材料和重新编号的部分），并由ANSI采纳。1999年，ISO发布了一个新的C标准，ANSI也采纳了它，使1989/1990年的标准正式过时。2011年末，ISO又发布了一个新的C标准，ANSI也采纳了它。除了第一个标准外，C标准最初都是由ISO出版的，最好按年份来引用这些标准。 - Keith Thompson

唉，仍然有一些编译器甚至不支持1999年的ISO C标准。对于1990年的标准，几乎普遍都有支持。 - Keith Thompson

非常对。编译器仍然没有实现C++ 89 - 我不知道C也要进行修订 - 我一直在专注于C ++ 0x（或现在称为C ++ 11）。似乎没有太多的变化 - 真是浪费时间。 - Adrian Cornish

Answer 1

如果你想生成文档，有许多不同的标准可供选择，可以尝试使用doxygen。

- Dhaivat Pandya

Answer 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
 */

(更多示例请参阅 doxygen手册)

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

apt-get install doxygen doxygen-gui graphviz

运行GUI调用doxywizard，并使用向导设置，只需在“专家”设置中设置JAVADOC_AUTOBRIEF。

- rubo77

---

一个带有示例的好答案。 - Drew

Answer 3

您的公司规定了标准，但是没有遵循这些标准。
创建项目文档的一种流行方式是使用 doxygen。

- Alok Save

Answer 4

一种选择是使用doxygen格式编写注释-这样做的好处是能够为您的代码生成html / latex和其他各种文档。

- Adrian Cornish