代码内文档（注释）的最常见/最喜欢的语法？答案

【问题标题】：Most common/liked syntax for in-code documentation (comments)?代码内文档（注释）的最常见/最喜欢的语法？
【发布时间】：2011-06-14 16:36:57
【问题描述】：

多年来，我一直在使用 Notepad++ 编写 PHP，但今天我下载了 Eclipse IDE。它的功能之一是自动完成某些“语法模式”，例如 cmets。我已经看到了很多不同的方法来将 cmets 和文档实现到 php 文件中，所以现在我开始想，我是否应该遵循 Eclipse 建议的语法。

我的意思是这样的：

你怎么看？

玛蒂莱恩

【问题讨论】：

【解决方案1】：

正如其他人所指出的，将这种 cmets 用于 phpdoc 可能非常有价值。但我认为这不仅是为了生成文档，而且还让你更容易编写代码。一些 IDE（至少 Netbeans）使用 phpdoc cmets 来提供比其他方式更好的自动完成功能。

【讨论】：

【解决方案2】：

Eclipse 最好使用heredoc/phpdoc cmets，然后可以将其编译成文档。尝试编写一个函数，然后在其上方添加 /** 注释，您会看到 ecplise 自动在注释中添加函数参数。

如果您查看 Java API，就会发现这是从这种 cmets 风格编译而来的文档。

如果您认为您永远不会将您的 cmets 编译成文档，那么不要觉得受它的束缚，代码中的额外 cmets 总是有用的。但是，它是一个文档标准，所以它不是一件坏事。我只倾向于对我知道很多其他人会关注的事情使用这种评论方式。

【讨论】：

【解决方案3】：

Eclipse 似乎采用了phpDoc（可能是 PHP 项目最常见的解决方案，我很乐意推荐一个）元素，这是一种记录各种类、方法、方法参数等的好方法。以及提供一种跟踪待办事项、将功能/方法标记为已弃用等的方法。

此外，您当然可以使用 phpdoc 命令行工具生成 HTML、PDF、CHM 格式等格式的文档

您可以在phpDoc site 上找到更多信息（并查看所需的语法）。

【讨论】：

【解决方案4】：

它是 phpdoc 格式，一种使用 cmets 自动记录代码的方法。

【讨论】：