完美解决phpdoc导出文档中@package的warning及Error的错误_php技巧

今天在编写PHPDoc的导出文档的时候发现一个很郁闷的错误，虽然这个warning不是什么重要错误，但是看着总是很不爽的。于是就去网上找了很多相关的资料，可是郁闷的是不知道是我用的PHPDoc版本太新（1.4的版本），还是说很多人都没遇到这个问题，反正就是没有相关的这个资料找到，只是找到了一些从PHPDocumentor官方网倒出来的关于@package的使用注意事项，然后就只能一条一条检查，看了一个版本又一个版本，总算是被我解决了。

而且发现该方案可以解决@package之类相关的错误提示：

出现的问题：

1、no @package tag was used in a DocBlock for XXXXXXXXXXX

2、XXXXXX has no page-level DocBlock, use @package in the first DocBlock to create one

3、ERROR： XXXX can not have @package tag。。。。（具体的提示我忘记了，大题的意思是这里的文档不能使用@package标签）

出现上诉问题的主要原因是：页面级的文档块注释解析错误

页面级文档注释：

必须是文件中的第一个文档块注释，并且有@package标签

该文档快注释之后如果是紧接着一段PHP代码或是class类申明，必须用文档块注释隔开（也就是说页面级文档块注释之后不能紧接着代码片段）

比如情况：

<span style="color: #ff0000"><strong>案例一： </strong></span> 
<span><u></u></span> 代码如下:<pre class="brush:php;toolbar:false layui-box layui-code-view layui-code-notepad"><ol class="layui-code-ol"><li>/** </li><li> * 这个是一个页面级文档块注释 </li><li> *@package haha </li><li> * </li><li> */ </li><li>class test { </li><li> </li><li>} </li><li> </li><li>以上的情况就会出现上述2的错误信息 </li><li>解决该案例的方案是给class重新声明一个文档块注释 </li><li><span><u></u></span> 代码如下:<pre class="brush:php;toolbar:false layui-box layui-code-view layui-code-notepad"><ol class="layui-code-ol"><li>/** </li><li> * 这个是一个页面级文档块注释 </li><li> *@package haha </li><li> * </li><li> */ </li><li>/** </li><li> * 我是test类 </li><li> */ </li><li>class test { </li><li> </li><li>} </li><li> </li><li>*********************************************** </li><li> </li><li><span style="color: #ff0000"><strong>案例二：</strong></span> </li><li><span><u></u></span> 代码如下:<pre class="brush:php;toolbar:false layui-box layui-code-view layui-code-notepad"><ol class="layui-code-ol"><li>/** </li><li> * 这个是一个页面级文档块注释 </li><li> */ </li><li> </li><li>/** </li><li> * 这个是一个页面级文档块注释 </li><li> *@package haha </li><li> * </li><li> */ </li><li>class test { </li><li> </li><li>} </li><li> </li><li>会出现如上问题中的1/2的情况。 </li><li>解决方案也是如案例一的解决方案一样 </li><li> </li><li>*********************************************** </li><li><span style="color: #ff0000"><strong>案例三： </strong></span> </li><li><span><u></u></span> 代码如下:<pre class="brush:php;toolbar:false layui-box layui-code-view layui-code-notepad"><ol class="layui-code-ol"><li>/** </li><li> * 这个是一个页面级文档块注释 </li><li> *@package haha </li><li> * </li><li> */ </li><li>define('yyyy', 'hahha'); </li><li> </li><li>就会出现如上所说的情况3Error。 </li><li>解决方案也是如出一则： </li><li><span><u></u></span> 代码如下:<pre class="brush:php;toolbar:false layui-box layui-code-view layui-code-notepad"><ol class="layui-code-ol"><li>/** </li><li> * 这个是一个页面级文档块注释 </li><li> *@package haha </li><li> */ </li><li>/** </li><li> * 我是常量 </li><li> */ </li><li>define('yyyy', 'hahha'); </li><li> </li></ol></pre></li><li><p>如果所写的文档块正确，就不会出现@package相关的错误了。</p></li><li><p><span style="color: #ff0000"><strong>注：</strong></span></p></li><li><p>1、在注释中需要注意，任何不是/**   */类型的注释都不会被PHPDoc所解析。而且/**  */中的多行注释前面不是以*开头的注释行也不会被解析。</p></li><li><p>2、如果声明了标签却没有给出相关的标签必选项就会发出一个Error信息，比如@var 后面没有变量，@return后面没有返回类型，都将会出现Error错误。解决方式就是补充完整，或是如果没有的话就移除。</p></li><li><p>另外，提供一个命令行方式下的命令文件执行，自动执行Doc文档生成：</p></li><li><pre class="brush:php;toolbar:false layui-box layui-code-view layui-code-notepad"><ol class="layui-code-ol"><li>@Rem: 命令行格式自动导出PHPDoc文档 </li><li>@Rem: author: 肖肖 x_824@sina.com </li><li>@echo off </li><li>@echo ******************************************************************************* </li><li>@echo 自动导出文档使用说明： </li><li>@echo 需要安装命令行的PHPDOCumentor,安装方式是用pear安装pear install PhpDocumentor即可 </li><li>@echo 1、option:设置导出文档的格式，命令行格式支持四种格式：默认为第一种格式 </li><li>@echo ###1】、HTML:frames:default </li><li>@echo ###2】、HTML:Smarty:default </li><li>@echo ###3】、CHM:default:default </li><li>@echo ###4】、PDF:default:default </li><li>@echo 2、dir:需要执行导出文档的目录、 </li><li>@echo 3、outputDir: 导出的文档存放目录 </li><li>@echo 4、title:导出的文档的标题 </li><li>@echo ******************************************************************************* </li><li> </li><li>@set option=HTML:frames:default </li><li>@set dir=D:\PHPAPP\test </li><li>@set outputDir=D:\PHPAPP\doc </li><li>@set title=PHPWindDoc </li><li> </li><li>@phpdoc -d %dir% -o %option% -ti %title% -t %outputDir% </li><li>@echo 欢迎使用！导出成功 </li><li>@pause </li><li></li></ol></pre></li><li><p><span style="color: #ff0000"><strong>注：</strong></span>该命令需要安装命令行下的PHPDocumentor包，安装方式用pear安装。</p></li><li><p>谨此！</p></li><li><p>以上这篇完美解决phpdoc导出文档中@package的warning及Error的错误就是小编分享给大家的全部内容了，希望能给大家一个参考，也希望大家多多支持脚本之家。                    </p></li></ol></pre></li></ol></pre></li></ol></pre></li></ol></pre>