PSR 5 PHP 注释 - 说明文档 「被拒绝」
1. 概要
PHPDoc 文档注释可以提供一种全面且灵活的方式来尽可能细致地描述软件系统。 例如，这种类型的注释文档可以帮助源代码的贡献者和使用者了解需要传递给特定方法的参数类型，或者如何能使用某个项目中的类
通过在源代码的文档中插入的特定标记，该部分源代码的文档就不会因为过时而产生太大的影响
PHPDoc 受到了 JavaDoc 的启发，作为一种注释格式已经存在了十多年了，目前该领域的大部分公开的 PHP 项目都在使用它
2. 何必?
PHPDocumentor 带头并促进了 PHPDoc 文档注释的发展，随着其它的越来越多的工具大力使用 PHPDoc 文档注释，制定一个官方的正式标准而不是基于当下提供的事实变得越来越重要
此 PSR 的另一个目的时是弃用过时的元素，引入新的概念和语法来反映 PHP 语言的当前状态，并促进使用当下和可见未来的最佳实践和设计模式
优点:
-
使用 PHPDoc 文档注释时，开发者 ( 使用者 ) 有一个共同的参考
-
项目和他们的开发者 ( 贡献者 ) 有一个可以咨询的权威参考
-
IDE 开发者可以通过标准化他们使用 PHPDoc 的方式来解决自动提示和代码跳转等问题
-
使用者很容易读懂使用 PHPDoc 文档注释的项目 ( 例如文档生成器或使用注释的应用程序 )
-
上述利益相关者可以自己定义或实现缺少的功能.
缺点:
-
如果 PHPDoc 文档注释中某个元素的使用方式与规范的不同，那么最好遵循本规范，这将耗费极大的成本
-
弃用常见的 PHPDoc 文档注释的元素的可能会导致对建议更改的混乱或抵制。出于这个原因，这些概念被弃用而不被删除
-
鉴于当前标准的使用范围，不可能同时兼顾不疏远现有用户或供应商和确保当前实践向后兼容方面引入重大突破同
3. 内容
3.1 目标
-
为 PHP 文档注释提供一份完整的技术定义或模式
scheme 应该怎么翻译？
-
引入符合当下和可预见的未来使用的最佳实践或设计模式的新概念
-
弃用被更新的概念所取代或在当今的 PHP 环境中不再使用的旧概念
3.2 非目标
-
这不是一份编码标准，因为该 PSR 没有提供关于如何及何时使用本文档中描述的概念的建议
-
此 PSR 允许使用 Symfony / Doctrine 样式注释中的符号来帮助注释的创建，但没有定义任何注释样式或使用已经存在的 "已定义的注释"。因为这已经超出了本 PSR 的范围
4. 方案
4.1 选择的方案
我们决定规范已经存在的实践，观察未记录的用法( 例如 Doctrine-style 注释格式 )，权衡使用文档生成器（ 例如 phpDocumentor ) 请求
为了减少可能的解释工作，这些组合应该足够详细
除此之外，作者还要考虑到未来的扩展和新增的标签不会对 PHPDoc 本身的语法产生任何影响
优点:
- 提供了一份机器可自动分析和验证的规范
- 考虑了众多的因数而形成的一个完整的提案
缺点:
- 太技术和太详细
- 只有在语法不受影响时才能扩展
5. 参与人员
5.1 撰稿者
- Chuck Burgess
5.2 发起人
- Michael Cullum
5.3 工作组成员
6. 表决结果
- Entrance Vote: TBD
- Acceptance Vote: TBD
7. 参考文章
此规范提到的大多数参考文章都在各自的章节中有提及，这里就不再罗列了
注意：顺序是按照时间顺序排列的