代码内文档（评论）最常见/最喜欢的语法？

Question

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

以下是我的意思：

您怎么看？

Martti Laine

Answer 1

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

http://www.phpdoc.org/

Answer 2

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

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

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

Answer 3

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

如果你看一下Java API，那就是那种从这种评论风格中编译的文档。

如果你认为你不打算将你的评论编译成文档，那么不要觉得受其约束，代码中的额外注释总是有用的。但是，它是一个文档标准，所以这不是一件坏事。我只倾向于使用这种评论方式来表达我认识很多其他人会看到的东西。

Answer 4

正如其他人所指出的那样，对phpdoc使用这种评论非常有价值。但我认为这不仅仅是关于生成文档，还使您更容易编写代码。一些IDE（至少是Netbeans）使用phpdoc注释来提供比其他方式更好的自动完成功能。