如何使php文档更接近标准？

Question

我有一个大型的php项目。我过去常常用NaturalDocs来记录它，但是我很长时间(几年)没有在构建过程中包含文档生成。

我最近开始使用composer并研究PSR。记录我的代码的唯一标准方法似乎是phpdocumentor的docblocks。

因为我的代码只是部分面向对象的，并且包含了很多过程文件，所以我不能只依赖于记录类和函数，但是我有很多文件级别的文档。

结果表明，phpdocumentor中不支持页面级的文档块(请参阅https://stackoverflow.com/questions/26925742/page-level-docblocks-and-phpdocumentor-templates )。所以我现在真的被困住了。

在结束我的问题时：

用docblocks和phpdocumentor记录非面向对象的代码是否有意义？phpdocs在这里是个不错的选择吗？我的项目文档专业化的方法是可行的，还是有某种缺陷？

Answer 1

我仍然认为坚持使用phpDoc来记录PHP代码是有意义的。这是php PSR项目推荐的标准。它也被推广到注释概念中，因为它是例如在学说中使用。phpDoc的另一个论点是Javascript和许多其他语言都有类似的注释系统。

在花了大量时间尝试phpDocumentor工作之后，我用含氧生成了文档。与phpDocumentor相比，有明显的优势：

• 它是从盒子里出来的。没有必要处理大量的bug。
• 灵活性: doxygen还有更多的选择。
• 页面级文档块可以在框内工作(使用@file启动文档块)。
• 可以记录所有实体，即使它们没有文档。这允许您获得项目中所有类、函数和vars的完整文档，而无需开始文档化。这符合干法原则，只允许你手动记录什么是重要的。你可以记录更大的图片，让DO2枚举所有的函数参数.
• 生成文档的速度更快
• 医生更好。

我发现的唯一缺点是，你不能把1比1的PSR-5标准提案：

• @var不赞成@type，但doxygen只理解@var。
• @file是必要的，但并不以标记phpDoc的形式存在。

但phpDocumentor也不符合phpDoc标准(例如，phpDocumentor不理解推荐的描述散列方式)。

结论

必须有完整的代码文档。它简化了工作，减轻了压力。

对我来说，文档是至关重要的，因此很难理解PHP框架互操作组发布关于文档的建议，而没有文档生成器能够做到这一点。