docs简介

很多语言都有通过代码注释（类注释、方法注释、成员注释）来生成接口文档的机制，比如java、php。这个机制包括两部分，一部分是代码注释的规范；一部分是生成文档的工具。就是说首先你要按照注释规范规定的风格书写注释，然后使用对应工具就可以生成接口文档（或者说说类结构描述文档）来供别人或自己查看。

php作为弱类型语言，phpDocs除了可以生成接口文档之外，还承载了语法检查等更重要的作用。因为是弱类型，所以没有在语言级别做某些限制，比如函数的参数签名中如果不声明变量类型，那么不管你传入的是什么类型的变量，则idea永远不会提示你代码异常，直到运行时报错。这在代码安全性上是很重要的问题。 

自动生成phpDocs

开发过程中我们可能习惯先写好方法签名才会写注释。当然手写注释非常麻烦，phpstorm提供了生成注释的功能，在类的任意部分（方法名前、类名前、成员名前）输入/**然后按回车即可自动生成docs。

自动更新phpDocs

写好的注释需要修改，比如要给一个方法新增一个参数，那么在参数签名中添加过此参数之后会发现phpstorm在此参数下划了黄色波浪线（给出警告），则在此参数上使用快捷键【自动补全】则会弹出自动更新phpdocs的选项，选择此选项即可自动更新docs，包括参数名，参数类型等。当然，当你重构参数名的时候，docs也会自动更新。

laravel中使用phpDocs提高开发效率

docs还有一个非常核心的功能就是代码提示。可以给类以phpDocs的方式提供成员声明。比如给类Person提供一个成员声明，则可以实现自动补全，给类提供方法docs也可以达到代码提示的效果，并且phpstorm将会自动将此成员认定为是类结构的一部分。比如下图中的Person类中的name成员。此成员支持重构。有些工具比如ide-helper就是使用此机制来提高laravel开发效率。

总结

phpDocs不仅能提高代码可读性，并且可以大幅提升开发效率和代码安全性。没有理由不用使用phpDocs，因为这是对php作为弱类型语言弱点的核心补充，可以说是接上了php的一条断腿。

题目说此特性是【躲在角落里的】是说明，很多人都没有认识到docs的重要性和在php生态中的核心性，这很可悲。

idea激活码 、phpstorm、pycharm、datagrip注册码获取 http://www.jetbrains-active.com/article/4.html