如果你留心的话,把鼠标放到某个系统函数上,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都删掉 */
效果: