PHP Doc

未结帖

 0 1708

carter 2017-08-13

悬赏：5飞吻

文档注释，无非“//”和“/**/”两种，自己写代码，就那么点，适当写几句就好了；但是一个人总有融入团队的一天，团队的交流不是那几句注释和一张嘴能解决的，还需要通用的注释标准。

PHPDoc是PHP文档注释的一个标准，可以帮助我们在注释文档时有规范，查看别人的代码时更方便。下面的表格是我翻译的WIKI上的PHPDoc，个人英文水平有限，可以参照原文。

文档翻译自：http://en.wikipedia.org/wiki/Phpdoc

标记	用途	描述
@abstract		抽象类的变量和方法
@access	public, private or protected	文档的访问、使用权限. @access private 表明这个文档是被保护的。
@author	张三 <zhangsan@163.com>	文档作者
@copyright	名称时间	文档版权信息
@deprecated	version	文档中被废除的方法
@deprec		同 @deprecated
@example	/path/to/example	文档的外部保存的示例文件的位置。
@exception		文档中方法抛出的异常，也可参照 @throws.
@global	类型：$globalvarname	文档中的全局变量及有关的方法和函数
@ignore		忽略文档中指定的关键字
@internal		开发团队内部信息
@link	URL	类似于license 但还可以通过link找到文档中的更多个详细的信息
@name	变量别名	为某个变量指定别名
@magic		phpdoc.de compatibility
@package	封装包的名称	一组相关类、函数封装的包名称
@param	如 [$username] 用户名	变量含义注释
@return	如返回bool	函数返回结果描述，一般不用在void（空返回结果的）的函数中
@see	如 Class Login（）	文件关联的任何元素（全局变量，包括，页面，类，函数，定义，方法，变量）。
@since	version	记录什么时候对文档的哪些部分进行了更改
@static		记录静态类、方法
@staticvar		在类、函数中使用的静态变量
@subpackage		子版本
@throws		某一方法抛出的异常
@todo		表示文件未完成或者要完善的地方
@var	type	文档中的变量及其类型
@version		文档、类、函数的版本信息

原文截图：

PHPDoc注释实例：

<?php
/**
 * start page for webaccess
 *
 * PHP version 5
 *
 * @category  PHP
 * @package   PSI_Web
 * @author    Michael Cramer <BigMichi1@users.sourceforge.net>
 * @copyright 2009 phpSysInfo
 * @license   http://opensource.org/licenses/gpl-2.0.php GNU General Public License
 * @version   SVN: $Id: class.Webpage.inc.php 412 2010-12-29 09:45:53Z Jacky672 $
 * @link      http://phpsysinfo.sourceforge.net
 */

/**
 * generate the dynamic webpage
 *
 * @category  PHP
 * @package   PSI_Web
 * @author    Michael Cramer <BigMichi1@users.sourceforge.net>
 * @copyright 2009 phpSysInfo
 * @license   http://opensource.org/licenses/gpl-2.0.php GNU General Public License
 * @version   Release: 3.0
 * @link      http://phpsysinfo.sourceforge.net
 */
class Webpage extends Output implements PSI_Interface_Output
{
    /**
     * configured language
     *
     * @var String
     */
    private $_language;

    /**
     * configured template
     *
     * @var String
     */
    private $_template;

    /**
     * all available templates
     *
     * @var Array
     */
    private $_templates = array();

    /**
     * all available languages
     *
     * @var Array
     */
    private $_languages = array();

    /**
     * check for all extensions that are needed, initialize needed vars and read config.php
     */
    public function __construct()
    {
        parent::__construct();
        $this->_getTemplateList();
        $this->_getLanguageList();
    }

    /**
     * checking config.php setting for template, if not supportet set phpsysinfo.css as default
     * checking config.php setting for language, if not supported set en as default
     *
     * @return void
     */
    private function _checkTemplateLanguage()
    {
        $this->_template = trim(PSI_DEFAULT_TEMPLATE);
        if (!file_exists(APP_ROOT . '/templates/' . $this->_template . ".css")) {
            $this->_template = 'phpsysinfo';
        }

        $this->_language = trim(PSI_DEFAULT_LANG);
        if (!file_exists(APP_ROOT . '/language/' . $this->_language . ".xml")) {
            $this->_language = 'en';
        }
    }

    /**
     * get all available tamplates and store them in internal array
     *
     * @return void
     */
    private function _getTemplateList()
    {
        $dirlist = CommonFunctions::gdc(APP_ROOT . '/templates/');
        sort($dirlist);
        foreach ($dirlist as $file) {
            $tpl_ext = substr($file, strlen($file) - 4);
            $tpl_name = substr($file, 0, strlen($file) - 4);
            if ($tpl_ext === ".css") {
                array_push($this->_templates, $tpl_name);
            }
        }
    }

    /**
     * get all available translations and store them in internal array
     *
     * @return void
     */
    private function _getLanguageList()
    {
        $dirlist = CommonFunctions::gdc(APP_ROOT . '/language/');
        sort($dirlist);
        foreach ($dirlist as $file) {
            $lang_ext = substr($file, strlen($file) - 4);
            $lang_name = substr($file, 0, strlen($file) - 4);
            if ($lang_ext == ".xml") {
                array_push($this->_languages, $lang_name);
            }
        }
    }

    /**
     * render the page
     *
     * @return void
     */
    public function run()
    {
        $this->_checkTemplateLanguage();

        $tpl = new Template("/templates/html/index_dynamic.html");

        $tpl->set("template", $this->_template);
        $tpl->set("templates", $this->_templates);
        $tpl->set("language", $this->_language);
        $tpl->set("languages", $this->_languages);

        echo $tpl->fetch();
    }
}

?>

PHP Doc

热忱回答（0）

最近热帖

近期热议