放牧代码和思想
专注自然语言处理、机器学习算法

eclipse PHP 的注释标签@*用法详解

如果你留心的话,把鼠标放到某个系统函数上,eclipse会自动给出该函数的参数、返回类型和解释。就像下图那样:

这是如何实现的呢?或者说我们写代码如何达到这个效果呢?其实看看eclipse的include文件就知道了:

/**
 * Checks whether a file or directory exists
 * @link http://www.php.net/manual/en/function.file-exists.php
 * @param filename string <p>
 * Path to the file or directory.
 * </p>
 * <p>
 * On windows, use //computername/share/filename or
 * \\computername\share\filename to check files on
 * network shares.
 * </p>
 * @return bool true if the file or directory specified by
 * filename exists; false otherwise.
 * </p>
 * <p>
 * This function will return false for symlinks pointing to non-existing
 * files.
 * </p>
 * <p>
 * This function returns false for files inaccessible due to safe mode restrictions. However these
 * files still can be included if
 * they are located in safe_mode_include_dir.
 * </p>
 * <p>
 * The check is done using the real UID/GID instead of the effective one.
 */
function file_exists ($filename) {}

在函数名的上面有一堆注释,这些注释使用了特殊的标签达到了图示的效果。这些标签是phpDocumentor定义的,包含了如下标签:

* 可用Tag列表: 
 * type 是PHP类型:integer, array, mixed, string等 
 * 
 * - @abstract
 * - @access       public or private
 * - @author       作者 <author@email> 
 * - @copyright    版权 
 * - @deprecated   废弃 
 * - @deprec       deprecated的简写 
 * - @example      指向例子 
 * - @exception    兼容javadoc 
 * - @global       type $globalvarname
 * - @global       type 函数中的全局变量描述 
 * - @ignore 
 * - @internal     给高级程序员看的内部细节描述 
 * - @param        type [$varname] 描述 
 * - @return       type 描述 
 * - @link         URL 
 * - @name         procpagealias [不懂] 
 * - @name         $globalvaralias
 * - @magic        兼容phpdoc.de 
 * - @package      包名 
 * - @see          指向其他元素的名字,如函数名,类方法等 
 * - @since        一个版本号或日期 
 * - @static
 * - @staticvar    type 函数中的静态变量的描述 
 * - @subpackage   子包 
 * - @throws       兼容Javadoc 
 * - @todo         待办列表,兼容phpdoc.de 
 * - @var          type    类变量的类型 
 * - @version      版本 
 */

注释还可以换行,语法跟html一样,你可以参考下面的网址了解更多:

http://sofire.iteye.com/blog/120007

http://lugir.com/story/290.html

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html

使用规范的tags就可以输出规范的文档了,php新手的话,有时候希望在注释里加上极具说明函数功能的话,这时候可以使用@tutorial 标签,比如:

/**
     * @param unknown $filename
     * @return boolean
     * @tutorial 删除文件,无论是bcs还是cache都删掉
     */

效果:

知识共享许可协议 知识共享署名-非商业性使用-相同方式共享码农场 » eclipse PHP 的注释标签@*用法详解

分享到:更多 ()

评论 欢迎留言

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址

我的开源项目

HanLP自然语言处理包基于DoubleArrayTrie的Aho Corasick自动机